# How the JSON Output Mode Serializes Download Information in you-get

> Learn how the JSON output mode in you-get serializes download information. Discover how it constructs a fake VideoExtractor and outputs metadata and stream URLs as a JSON object.

- Repository: [Mort Yao/you-get](https://github.com/soimort/you-get)
- Tags: internals
- Published: 2026-03-06

---

**When you run you-get with `--json`, the tool constructs a fake `VideoExtractor` object containing metadata and stream URLs, then serializes specific fields—`url`, `title`, `site`, `streams`, and optional `extra`—into a JSON object via `json_output.output()` instead of downloading files.**

The `soimort/you-get` command-line utility provides a **JSON output mode** that extracts video metadata and download URLs without performing actual downloads. This feature routes the download workflow through a dedicated serialization module that converts internal `VideoExtractor` objects into structured JSON data suitable for scripting and automation.

## How the JSON Flag Redirects the Download Workflow

In [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py), the command-line argument `--json` sets an internal `json_output` flag at lines 993–996. When this flag is `True`, you-get bypasses the standard printing and downloading logic entirely and delegates output handling to the [`src/you_get/json_output.py`](https://github.com/soimort/you-get/blob/main/src/you_get/json_output.py) module.

- If `json_output` is enabled, calls to download functions are intercepted.
- The `json_output.download_urls()` function creates a temporary extractor object rather than initiating file transfers.
- All JSON-specific logic remains isolated in [`json_output.py`](https://github.com/soimort/you-get/blob/main/json_output.py), leaving the core extractor code unchanged.

## Constructing the VideoExtractor Object for JSON Output

The `json_output.download_urls()` function (lines 49–66 in [`src/you_get/json_output.py`](https://github.com/soimort/you-get/blob/main/src/you_get/json_output.py)) builds a fake `VideoExtractor` instance to hold download metadata. This object mimics the structure used during actual downloads but contains only serialization-relevant fields:

```python
ve = last_info  # Reused from previous print_info call or newly created

stream = {}
stream['container'] = ext          # File extension (e.g., 'mp4')

stream['size'] = total_size        # Size in bytes (may be None)

stream['src'] = urls               # List of real URLs to download

if refer:
    stream['refer'] = refer
stream['video_profile'] = '__default__'
ve.streams = {'__default__': stream}
output(ve)  # Serialize to JSON

```

This temporary structure captures the **container type**, **file size**, **source URLs**, and **referer** information that the regular download workflow would use, packaging it into the `ve.streams` dictionary under the `__default__` key.

## Serializing Metadata to JSON

The `json_output.output()` function (lines 7–34 in [`src/you_get/json_output.py`](https://github.com/soimort/you-get/blob/main/src/you_get/json_output.py)) converts the `VideoExtractor` into a plain Python dictionary and emits it via `json.dumps()`. The serialization captures both mandatory and optional fields:

**Base fields always included:**
- `url` – The original video URL(s) from `ve.url`
- `title` – The extracted video title from `ve.title`
- `site` – The site identifier from `ve.name`
- `streams` – The complete mapping of quality profiles to stream data

**Optional fields added when present:**
- `audiolang` – Included if `ve.audiolang` exists on the extractor
- `extra` – A nested object containing `referer` and/or `ua` (user-agent) strings when available

The output format depends on the `pretty_print` argument: if `True`, the JSON uses `indent=4` for readability; otherwise, it outputs compact, single-line JSON.

## JSON Schema and Structure

A typical JSON output from you-get follows this deterministic structure:

```json
{
    "url": "https://example.com/video/12345",
    "title": "Sample Video",
    "site": "youtube",
    "streams": {
        "__default__": {
            "container": "mp4",
            "size": 12345678,
            "src": ["https://cdn.example.com/vid12345.mp4"],
            "video_profile": "__default__"
        }
    },
    "extra": {
        "referer": "https://example.com/",
        "ua": "Mozilla/5.0 …"
    }
}

```

The `streams` object may contain multiple keys beyond `__default__` if the specific site extractor populates different quality profiles (e.g., `720p`, `1080p`) before calling the JSON output functions. Each stream entry maintains the same schema: `container`, `size`, `src`, and `video_profile`.

## Info-Only Mode vs Full Download Metadata

When `--json` is combined with `--info` (or `-i`), you-get invokes `json_output.print_info()` at lines 40–47 instead of `download_urls()`. This creates a minimal `VideoExtractor` containing only the `site` and `title` fields, with no `streams` data.

The resulting JSON contains only:
- `url`
- `title`
- `site`

This mode is useful for quickly identifying videos and checking availability without fetching stream URLs or file metadata.

## Practical Usage Examples

Generate complete download metadata including stream URLs:

```bash
you-get --json "https://www.youtube.com/watch?v=abcd1234"

```

Fetch only basic video information without stream details:

```bash
you-get -i --json "https://vimeo.com/567890"

```

Both commands output valid JSON to stdout, with the first example including the full `streams` array containing actual CDN URLs ready for external download tools.

## Summary

- **Flag handling**: The `--json` argument in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py) (lines 993–996) redirects output to the JSON serialization module.
- **Object construction**: `json_output.download_urls()` builds a temporary `VideoExtractor` with `__default__` stream data including `container`, `size`, and `src` URLs.
- **Serialization**: `json_output.output()` converts the extractor to a dictionary with fields `url`, `title`, `site`, `streams`, and optional `audiolang`/`extra` metadata.
- **Dual modes**: Full metadata mode includes stream URLs, while info-only mode (`-i --json`) outputs only title and site identification.
- **Implementation**: All JSON logic is isolated in [`src/you_get/json_output.py`](https://github.com/soimort/you-get/blob/main/src/you_get/json_output.py), maintaining clean separation from download and extraction code.

## Frequently Asked Questions

### What fields are included in you-get's JSON output?

The JSON object always includes `url`, `title`, `site`, and `streams`. The `streams` object maps quality profiles to objects containing `container` (file extension), `size` (bytes), `src` (URL list), and `video_profile`. Optional fields include `audiolang` for multi-language videos and `extra` (containing `referer` and `ua`) when the extractor provides HTTP headers.

### How do I enable JSON output mode in you-get?

Append the `--json` flag to any you-get command. For metadata-only output without stream URLs, combine it with `--info` or `-i`. According to the source code in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py), this sets the internal `json_output` flag and routes calls through [`src/you_get/json_output.py`](https://github.com/soimort/you-get/blob/main/src/you_get/json_output.py) instead of the standard download pipeline.

### Why does the JSON output use `__default__` as a stream key?

The `json_output.download_urls()` function creates a single-entry `streams` dictionary with the key `__default__` to maintain compatibility with the `VideoExtractor` structure used throughout you-get. If a site extractor populates multiple quality profiles before JSON serialization, additional keys (e.g., `720p`, `1080p`) will appear alongside `__default__`.

### Where is the JSON serialization logic located?

All JSON-specific functionality resides in [`src/you_get/json_output.py`](https://github.com/soimort/you-get/blob/main/src/you_get/json_output.py). This module contains three primary functions: `output()` (handles the actual `json.dumps` conversion), `download_urls()` (builds the fake extractor for full metadata), and `print_info()` (creates minimal extractors for info-only mode). The module is called conditionally from [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py) when the `--json` flag is detected.