When you download a transcript from YTCaptions, you choose between two output formats: Markdown and JSON. Both contain the same underlying information — the full transcript plus the video's metadata — but they are structured differently and optimized for different use cases.

Here is exactly what each format produces, and how to decide which one to use.

What the Markdown Format Produces

Markdown output is a structured, human-readable document. A typical file looks like this:

# Video Title Here
**Channel:** Channel Name
**Views:** 1,234,567
**Published:** January 15, 2026
**URL:** https://www.youtube.com/watch?v=...

---
## Description

Full video description as written by the channel owner, including any links
and chapter markers they included.

---
## Transcript

[00:00] Hello and welcome back to the channel.
[00:04] Today we are going to walk through the complete setup process.
[00:09] By the end of this tutorial you will have everything running.

Each transcript line includes a timestamp in [MM:SS] format, letting you navigate back to the exact moment in the video when something was said. The metadata block at the top gives you source context at a glance.

Markdown renders cleanly in any Markdown-aware application: Obsidian, Notion, Bear, GitHub, VS Code with a Markdown preview, Typora, and most documentation tools. It also reads well as plain text without any rendering.

What the JSON Format Produces

JSON output is a machine-readable structured file where every metadata field is a discrete, addressable key:

{
  "video_id": "abc123xyz",
  "language": "English",
  "language_code": "en",
  "title": "Video Title Here",
  "channel": "Channel Name",
  "views": 1234567,
  "publish_date": "January 15, 2026",
  "url": "https://www.youtube.com/watch?v=abc123xyz",
  "thumbnail": "https://i.ytimg.com/vi/abc123xyz/maxresdefault.jpg",
  "description": "Full video description...",
  "transcript": "Hello and welcome back to the channel. Today we are going to..."
}

The transcript field in JSON is a clean string without timestamp markers — the full spoken text as a single continuous block, ready for programmatic processing. The thumbnail URL is included as a direct link, which is not present in the Markdown output.

When to Use Markdown

Markdown is the right choice when a human is going to read or work with the transcript directly:

  • Reading and review — the rendered format is clean and comfortable to read at length
  • Publishing to a blog — Markdown pastes directly into most CMS platforms and static site generators without reformatting
  • Note-taking apps — Obsidian, Notion, and Bear handle Markdown natively; the document imports with structure intact
  • Sharing with collaborators — Markdown is readable even without rendering, making it safe to share with non-technical colleagues
  • Reference with timestamps — the [MM:SS] markers in each line let you navigate back to specific video moments while reading

When to Use JSON

JSON is the right choice when a tool or a script is going to process the transcript:

  • Automation workflows — tools like n8n, Zapier, and Make can parse JSON fields directly, routing the title to one destination, the transcript to another, and the metadata to a database row, all in the same workflow
  • AI and LLM pipelines — structured JSON is straightforward to pass to language models for summarization, question generation, or analysis
  • Database ingestion — each metadata field maps cleanly to a database column without any parsing logic
  • Custom scripts — Python's json.loads() gives immediate access to every field; no regex or text parsing required
  • Thumbnail access — the JSON output includes the video thumbnail as a direct URL, which is useful for display in applications or dashboards

A Practical Rule of Thumb

If you are going to read the transcript, use Markdown. If a machine is going to read it, use JSON.

For most individual users — students, writers, researchers, and content creators — Markdown is the appropriate default. It is immediately readable, works in virtually any text application, and preserves the timestamps that let you verify and navigate the source.

For developers, automation engineers, and anyone building a processing pipeline, JSON provides the structured access that makes the data easy to route, query, and transform without writing a parser for Markdown formatting.

Both formats contain the same underlying data. If you download in one format and realize you need the other, you can re-run the same URL with a different format selection — the result will be identical content in the alternate structure.