media2md 0.9.12

Local-first CLI for turning Instagram, YouTube, TikTok, and Bilibili content into structured Markdown.

Media2MD

A local-first CLI for turning creator content into Markdown for humans, agents, and knowledge workflows.

Media2MD collects content from Instagram, YouTube, TikTok, and Bilibili, extracts captions, OCR text, or speech transcripts on your own machine, and writes the result as structured Markdown.

It is built for a different job than a normal downloader: follow creators over time, refresh saved catalogs, process backlogs, and turn platform content into durable local files that can be searched, summarized, archived, or fed into a wiki, RAG pipeline, or agent workflow.

Why Media2MD

• Local-first: OCR, transcription, and runtime state stay on your own machine
• Creator-oriented: track creators and process saved backlogs, not just one URL at a time
• Markdown-first: output is easy to archive, diff, search, and reuse
• Agent-ready: stable command surfaces and machine-readable ndjson output
• Runtime/code separation: installed package code and managed runtime state are kept separate
• Caption-first where possible: prefers captions and subtitles before falling back to local transcription

Supported Platforms

• Instagram
  • reels
  • posts
  • carousel posts
  • optional local OCR for post images
• YouTube
• TikTok
• Bilibili

Install

Base install:

pip install media2md

media2md base install gives you the core CLI, runtime management, health checks, update flow, and documentation-driven setup. Provider-specific collection, OCR, and transcription features require the matching extras below.

Or install by agent, give it this repo doc and ask it to follow it:

Read https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_INSTALL.md and install, initialize, verify auth, and validate the Media2MD setup on this machine. Do not ask for passwords, do not bypass 2FA/CAPTCHA, and stop if manual login is required.

Provider extras:

pip install "media2md[instagram]"
pip install "media2md[youtube]"
pip install "media2md[tiktok]"
pip install "media2md[bilibili]"
pip install "media2md[all]"

Instagram post OCR:

pip install "media2md[instagram,ocr-mac-os]"
pip install "media2md[instagram,ocr-windows-linux]"

Check the installed version:

media2md version

Default managed runtime location for a fresh install:

~/Downloads/media2md

Change it later if needed:

media2md runtime set-base-path <path>

Quick Start

Initialize the runtime:

media2md init --language <language> --markdown-language <markdown-language> --timezone <timezone> --non-interactive

Supported language values:

en
ja
zh-TW
zh-CN

Use IANA timezone names such as:

Asia/Tokyo
Asia/Taipei
America/Los_Angeles
Europe/London

Examples:

media2md init --language ja --markdown-language ja --timezone Asia/Tokyo --non-interactive
media2md init --language zh-TW --markdown-language zh-TW --timezone Asia/Taipei --non-interactive
media2md init --language en --markdown-language en --timezone America/Los_Angeles --non-interactive

Connect provider auth:

If auth accounts or auth connect says no platform cookies were found, open the selected browser profile and log in first:

media2md auth login <provider> --browser chrome

Then rerun auth accounts, auth connect, and auth verify for that provider.

YouTube:

media2md auth profiles youtube --browser chrome
media2md auth accounts youtube --browser chrome --profile Default
media2md auth connect youtube --browser chrome --profile Default
media2md auth verify youtube

auth accounts youtube prints copy-paste-ready follow-up commands. Today it reports the effective YouTube session Media2MD can resolve from the selected browser profile; full in-profile multi-account enumeration is not yet available. It also prints an explicit --account <account-key> command when you want to pin the resolved session key.

Instagram:

media2md auth profiles instagram --browser chrome
media2md auth accounts instagram --browser chrome --profile Default
media2md auth connect instagram --browser chrome --profile Default
media2md auth verify instagram

auth accounts instagram prints ready-to-run follow-up commands, including an explicit account-pinning form when you want Media2MD to bind to the currently resolved session key. Full Instagram multi-account enumeration is not yet available; the current flow reports the effective session Media2MD can resolve from the selected browser profile.

TikTok:

media2md auth profiles tiktok --browser chrome
media2md auth accounts tiktok --browser chrome --profile Default
media2md auth connect tiktok --browser chrome --profile Default
media2md auth verify tiktok

auth accounts tiktok prints copy-paste-ready follow-up commands. Today it reports the effective TikTok session Media2MD can resolve from the selected browser profile; full in-profile multi-account enumeration is not yet available. It also prints an explicit --account <account-key> command when you want to pin the resolved session key.

Bilibili:

media2md auth profiles bilibili --browser chrome
media2md auth accounts bilibili --browser chrome --profile Default
media2md auth connect bilibili --browser chrome --profile Default
media2md auth verify bilibili
media2md doctor bilibili-access --video-id <BV_VIDEO_ID>

auth accounts bilibili reports the effective Bilibili session Media2MD can resolve from the selected browser profile. It also prints an explicit --account <account-key> command when you want to pin the resolved session key.

Switch or clear a saved auth binding:

media2md auth disconnect instagram --yes
media2md auth connect instagram --browser chrome --profile Default

Track a creator and process content:

media2md creator add https://www.youtube.com/@creator-name --provider youtube
media2md creator refresh-catalog @creator-name --provider youtube --force-full
media2md creator run @creator-name --provider youtube

Check status:

media2md status
media2md doctor all

Common direct shortcuts:

media2md settings
media2md auth
media2md creator
media2md media
media2md update
media2md doctor
media2md runtime

These map to safe read-only defaults such as settings show, auth status, creator status, media list, update check, doctor all, and runtime status. Bare scheduler, repair, and data print help and still require an explicit subcommand.

Common Workflows

Single URL:

media2md media inspect <media-url>
media2md media add <media-url> --process-now

Drain a backlog:

media2md creator run @creator-name --provider youtube --mode drain --batch-size 1 --max-batches 5

Runtime paths:

media2md runtime status
media2md runtime base-path
media2md runtime path

Docs

• Human setup: First Run Guide
• Agent setup: Agent Install Guide
• Agent operations: AGENT_OPERATIONS.md
• Agent auth selection policy: AGENT_AUTH_SELECTION_POLICY.md
• Agent decision map: AGENT_DECISION_MAP.md
• Agent task prompts: AGENT_TASK_PROMPTS.md
• Full command reference: CLI Reference
• Release process: RELEASE_PROCESS.md

Good Fit

Media2MD is a strong fit when you want to:

• follow creators over time instead of manually checking feeds
• build a local Markdown archive from social and video content
• feed normalized Markdown into search, notes, RAG, or agent workflows
• keep processing on your own machine instead of relying on a hosted service

It is a weaker fit when you need:

• a hosted SaaS workflow
• remote browser login automation
• challenge bypasses or account-evasion tooling
• a cloud-managed ingestion service

Safety

Media2MD does not type passwords, bypass 2FA, solve CAPTCHA, or defeat provider access controls. It works best when the target account session is already healthy in a local browser profile that you explicitly choose.

Links

• Repository: danielcanfly/media2md
• PyPI: media2md
• First Run Guide: docs/FIRST_RUN.md
• Agent Install Guide: docs/AGENT_INSTALL.md
• Agent Operations Guide: docs/AGENT_OPERATIONS.md
• Agent Auth Selection Policy: docs/AGENT_AUTH_SELECTION_POLICY.md
• Agent Decision Map: docs/AGENT_DECISION_MAP.md
• Agent Task Prompts: docs/AGENT_TASK_PROMPTS.md
• CLI Reference: docs/CLI_REFERENCE.md
• Release Process: docs/RELEASE_PROCESS.md
• Changelog: CHANGELOG.md
• Contributing: CONTRIBUTING.md