media2md 0.9.5

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

Media2MD

Media2MD is a local-first CLI for collecting content from Instagram, YouTube, and TikTok, transcribing speech on your own machine, and turning the results into structured Markdown.

It is designed for both direct terminal use and agent-driven workflows that need stable commands, schedulable operations, and machine-readable output. The generated Markdown is meant to be easy to archive, search, summarize, or feed into a wiki or knowledge base.

Media2MD runs locally, can reuse a browser session you already authenticated on your machine, and keeps runtime state separate from the installed package. It does not enter passwords, bypass 2FA, solve CAPTCHAs, or defeat platform challenges.

Highlights

• One CLI for Instagram, YouTube, and TikTok intake
• Local runtime and local transcription workflows
• Instagram support for reels, single-image posts, and carousel posts
• Markdown output that is easy to archive, search, summarize, or import into a knowledge base
• Creator tracking, catalog refresh, queue processing, diagnostics, and backup commands in one tool
• Human-friendly terminal usage plus stable surfaces for automation and agent orchestration

What It Is For

Media2MD is useful when you want to:

• track specific creators over time instead of checking them manually
• let an agent run scheduled collection and follow-up workflows
• turn media output into Markdown that can later be organized into a wiki or knowledge base
• process content on your own machine instead of depending on a hosted external service

The current agent-oriented scheduling and adaptation work is primarily aligned with OpenClaw-based workflows.

Install

Install the base package:

pip install media2md

Install provider extras when needed:

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

Install Instagram post OCR support when you want OCR from post images:

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

Use ocr-mac-os on macOS. Use ocr-windows-linux on Windows or Linux.

Check the installed version:

media2md version

Quick Start

Initialize the managed runtime:

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

Supported language values:

en
ja
zh-TW
zh-CN

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 <timezone> --non-interactive

Connect and verify provider auth:

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

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

Inspect your runtime and health status:

media2md status
media2md doctor all
media2md runtime base-path
media2md runtime path

Common Workflows

Add a creator and refresh the creator catalog:

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

Process a creator queue into Markdown:

media2md creator run @creator-name --provider youtube
media2md status --output ndjson

Process a single media URL immediately:

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

Instagram media URLs can be reels, posts, legacy /tv/ video URLs, or carousel posts. Post and carousel Markdown includes the caption plus OCR text grouped in image order when OCR support is installed.

Create and verify a state backup:

media2md data backup --destination ~/media2md-backups
media2md data verify-backup ~/media2md-backups/media2md-state-YYYYMMDDTHHMMSSZ.zip

Creator inputs can be either full creator URLs or provider-qualified handles. For bare handles such as @creator-name or creator-name, pass --provider explicitly so the CLI knows which platform to target.

media2md creator refresh-catalog is the preferred public command name for refreshing a creator catalog. media2md creator sync still exists in the full CLI surface for lower-level use.

Output and Runtime

New installs default to ~/Downloads/media2md. Existing installs that already use an older managed location keep that location until you explicitly move them.

Useful runtime commands:

media2md runtime status
media2md runtime base-path
media2md runtime path
media2md runtime set-base-path <path>
media2md runtime install --force

Typical Markdown output paths:

markdown/youtube/<creator>/videos/
markdown/youtube/<creator>/shorts/
markdown/instagram/<creator>/reels/
markdown/instagram/<creator>/posts/
markdown/tiktok/<creator>/

Documentation

• First Run Guide
• CLI Reference
• Release Process
• Changelog

CLI Areas

• auth: browser profile discovery, connection, verification, refresh, and status
• creator: add creators, refresh catalogs, inspect status, set policies, and run processing
• media: inspect URLs, add media, process registered items, and list tracked entries
• doctor: environment, provider, and access diagnostics
• data: backup, backup verification, and destructive data operations
• runtime: managed runtime install, import, and path/status helpers
• scheduler: scheduled processing entrypoints
• update: package update and rollback helpers

For machine-readable integrations, many commands support --output ndjson.

media2md doctor instagram-backends also reports the current Instagram OCR route and whether local post OCR is ready on this machine.

Example Commands

Check system-wide status:

media2md status
media2md status --output ndjson

Show or change settings:

media2md settings show
media2md settings set --instagram-backend auto --youtube-caption-first --update-check-on-use

Set creator policy:

media2md creator policy set <creator> --provider <provider> \
  --batch-size-type <type-a>=<limit-a> \
  --batch-size-type <type-b>=<limit-b> \
  --batch-size-type <type-c>=<limit-c> \
  --scheduled-processing

Run the scheduler tick manually:

media2md scheduler tick --non-interactive --output ndjson

See the full command reference in docs/CLI_REFERENCE.md.

Typical Use Cases

Media2MD is a good fit when you want to:

• archive creator output into Markdown on your own machine
• build a personal or team knowledge base from social/video content
• inspect or process specific URLs without building your own scraping pipeline
• feed normalized Markdown artifacts into downstream agent or search workflows

It is a weaker fit when you need:

• a hosted SaaS workflow
• remote browser automation for account login
• bypasses for provider auth or challenge mechanisms
• a fully managed cloud ingestion service

What It Does Not Do

Media2MD does not:

• type passwords for you
• bypass 2FA, CAPTCHA, or account challenges
• turn private platform access into public access
• remove the need to follow platform terms, copyright rules, privacy rules, or local law

Notes

• Some providers require their corresponding extra dependencies.
• Instagram post and carousel OCR uses local OCR only. No external OCR API or LLM service is required.
• Browser-backed auth works best when the target session is already healthy in the browser.
• The managed runtime separates code from state to make local upgrades and recovery easier.
• The package is published on PyPI, but your actual media processing happens locally.

Project Status

Current published version: 0.9.5

Recent release themes in 0.9.x include:

• stronger TikTok transport and metadata fallback handling
• more truthful health and degraded-ready reporting
• safer backup and runtime integrity behavior
• tighter regression coverage for acceptance-derived failures

See the Changelog for version-by-version details.

Contributing

See CONTRIBUTING.md.

Links

• Repository: danielcanfly/media2md
• PyPI: media2md
• Issues: GitHub Issues
• Changelog: CHANGELOG.md

Responsible Use

Only download content you own, are authorized to process, or may lawfully archive. Platform terms, copyright, privacy, and local laws still apply.