Metadata-Version: 2.4
Name: media2md
Version: 0.9.15
Summary: Local-first CLI for turning Instagram, YouTube, TikTok, and Bilibili content into structured Markdown.
Project-URL: Homepage, https://github.com/danielcanfly/media2md
Project-URL: Repository, https://github.com/danielcanfly/media2md
Project-URL: Issues, https://github.com/danielcanfly/media2md/issues
Project-URL: Changelog, https://github.com/danielcanfly/media2md/blob/main/CHANGELOG.md
Author: Daniel Huang
License: MIT License
        
        Copyright (c) 2026 Daniel Huang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Keywords: agent,bilibili,instagram,markdown,openclaw,tiktok,whisper,youtube
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.11
Provides-Extra: all
Requires-Dist: bilibili-api-python>=17.4.2; extra == 'all'
Requires-Dist: browser-cookie3>=0.20; extra == 'all'
Requires-Dist: easyocr>=1.7.2; extra == 'all'
Requires-Dist: gallery-dl>=1.32; extra == 'all'
Requires-Dist: httpx>=0.28; extra == 'all'
Requires-Dist: instaloader>=4.15; extra == 'all'
Requires-Dist: mlx-whisper>=0.4; (platform_system == 'Darwin' and platform_machine == 'arm64') and extra == 'all'
Requires-Dist: pyyaml>=6.0; extra == 'all'
Requires-Dist: yt-dlp[curl-cffi,default]>=2026.1.1; extra == 'all'
Provides-Extra: auth-browser
Requires-Dist: browser-cookie3>=0.20; extra == 'auth-browser'
Provides-Extra: bilibili
Requires-Dist: bilibili-api-python>=17.4.2; extra == 'bilibili'
Requires-Dist: httpx>=0.28; extra == 'bilibili'
Requires-Dist: yt-dlp[curl-cffi,default]>=2026.1.1; extra == 'bilibili'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Provides-Extra: instagram
Requires-Dist: browser-cookie3>=0.20; extra == 'instagram'
Requires-Dist: gallery-dl>=1.32; extra == 'instagram'
Requires-Dist: instaloader>=4.15; extra == 'instagram'
Requires-Dist: pyyaml>=6.0; extra == 'instagram'
Provides-Extra: mlx
Requires-Dist: mlx-whisper>=0.4; (platform_system == 'Darwin' and platform_machine == 'arm64') and extra == 'mlx'
Provides-Extra: ocr-mac-os
Requires-Dist: easyocr>=1.7.2; (platform_system == 'Darwin') and extra == 'ocr-mac-os'
Provides-Extra: ocr-windows-linux
Requires-Dist: easyocr>=1.7.2; (platform_system != 'Darwin') and extra == 'ocr-windows-linux'
Provides-Extra: openclaw
Provides-Extra: tiktok
Requires-Dist: browser-cookie3>=0.20; extra == 'tiktok'
Requires-Dist: yt-dlp[curl-cffi,default]>=2026.1.1; extra == 'tiktok'
Provides-Extra: youtube
Requires-Dist: browser-cookie3>=0.20; extra == 'youtube'
Requires-Dist: yt-dlp[curl-cffi,default]>=2026.1.1; extra == 'youtube'
Description-Content-Type: text/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.

## Account Safety Disclaimer

- You can use Media2MD without logging in and should prefer public or unauthenticated flows when they are sufficient.
- If you choose to sign in to a platform, do not use a primary personal or business account. Use a disposable account only.
- Platform login, cookie reuse, and authenticated session refresh can trigger platform bot-detection, anti-abuse, or account review mechanisms.
- Media2MD does not accept responsibility for platform enforcement, lockouts, bans, rate limits, or other account consequences.

## 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

## Public Access and Fallback Matrix

| Platform | Can it sometimes work without login? | Public degraded fallback implemented? | Current fallback scope | Important limits |
| --- | --- | --- | --- | --- |
| Instagram | Yes, sometimes | Yes | Public HTML degraded fallback for `post` only | Preview-level only. Not a full carousel guarantee. No degraded fallback for reels or TV. Public HTML availability varies by post and user-agent. |
| YouTube | Yes, often | No | None | Public videos often work without login, but availability still depends on the video, region, age-gating, and current platform restrictions. |
| TikTok | Yes, sometimes | No | None | Public access is inconsistent and often affected by anti-bot or anti-abuse controls. No degraded HTML fallback is implemented. |
| Bilibili | Yes, sometimes | No | None | Some public items work without login, but subtitles, audio streams, account state, membership rules, or region rules may still require a valid session. |

What this means in practice:

- Only Instagram currently has a built-in degraded fallback path after primary metadata backends fail.
- That Instagram fallback is intentionally partial and honest: it can return a preview image and a public description, but it does not claim full asset completeness.
- The other platforms may still work without login through their normal public collection paths, but they do not have an extra degraded fallback layer yet.

## Install

Base install:

```bash
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:

```text
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:

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

Instagram post OCR:

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

Check the installed version:

```bash
media2md version
```

Default managed runtime location for a fresh install:

```text
~/Downloads/media2md
```

Change it later if needed:

```bash
media2md runtime set-base-path <path>
```

## Quick Start

Initialize the runtime:

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

Supported language values:

```text
en
ja
zh-TW
zh-CN
```

Use IANA timezone names such as:

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

Examples:

```bash
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:

Before any platform login or authenticated session connect, Media2MD now asks whether you want to proceed. The safe default is to choose not to log in and continue with unauthenticated/public flows only.

If you do choose to sign in, do not use a primary account. Use a disposable account only. Platform login or authenticated session reuse may trigger bot-detection or other enforcement actions, and Media2MD does not accept responsibility for those consequences.

Auth behavior by mode:

- Interactive human use: `auth login` and `auth connect` show a warning first and let you choose not to log in.
- Non-interactive or agent use: `auth login` and `auth connect` exit safely unless you pass `--acknowledge-platform-risk`.
- This risk gate applies to Instagram, YouTube, TikTok, and Bilibili.
- Exception: `media2md auth login youtube` still does not open a Google login window. For YouTube, use `auth profiles`, `auth accounts`, `auth connect`, and `auth verify`.

Human-friendly auth commands:

```bash
media2md auth profiles <provider> --browser chrome
media2md auth accounts <provider> --browser chrome --profile Default
media2md auth connect <provider> --browser chrome --profile Default
media2md auth verify <provider>
```

Agent or non-interactive auth commands:

```bash
media2md auth profiles <provider> --browser chrome --output ndjson
media2md auth accounts <provider> --browser chrome --profile Default --output ndjson
media2md auth connect <provider> --browser chrome --profile Default --acknowledge-platform-risk
media2md auth verify <provider> --output ndjson
```

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

```bash
media2md auth login <provider> --browser chrome
```

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

YouTube:

```bash
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
```

Agent / non-interactive:

```bash
media2md auth profiles youtube --browser chrome --output ndjson
media2md auth accounts youtube --browser chrome --profile Default --output ndjson
media2md auth connect youtube --browser chrome --profile Default --acknowledge-platform-risk
media2md auth verify youtube --output ndjson
```

`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:

```bash
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
```

Agent / non-interactive:

```bash
media2md auth profiles instagram --browser chrome --output ndjson
media2md auth accounts instagram --browser chrome --profile Default --output ndjson
media2md auth connect instagram --browser chrome --profile Default --acknowledge-platform-risk
media2md auth verify instagram --output ndjson
```

`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:

```bash
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
```

Agent / non-interactive:

```bash
media2md auth profiles tiktok --browser chrome --output ndjson
media2md auth accounts tiktok --browser chrome --profile Default --output ndjson
media2md auth connect tiktok --browser chrome --profile Default --acknowledge-platform-risk
media2md auth verify tiktok --output ndjson
```

`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:

```bash
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>
```

Agent / non-interactive:

```bash
media2md auth profiles bilibili --browser chrome --output ndjson
media2md auth accounts bilibili --browser chrome --profile Default --output ndjson
media2md auth connect bilibili --browser chrome --profile Default --acknowledge-platform-risk
media2md auth verify bilibili --output ndjson
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:

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

Track a creator and process content:

```bash
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:

```bash
media2md status
media2md doctor all
```

Common direct shortcuts:

```bash
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:

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

Drain a backlog:

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

Runtime paths:

```bash
media2md runtime status
media2md runtime base-path
media2md runtime path
```

## Docs

- Human setup: [First Run Guide](https://github.com/danielcanfly/media2md/blob/main/docs/FIRST_RUN.md)
- Agent setup: [Agent Install Guide](https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_INSTALL.md)
- Agent operations: [AGENT_OPERATIONS.md](https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_OPERATIONS.md)
- Agent auth selection policy: [AGENT_AUTH_SELECTION_POLICY.md](https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_AUTH_SELECTION_POLICY.md)
- Agent decision map: [AGENT_DECISION_MAP.md](https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_DECISION_MAP.md)
- Agent task prompts: [AGENT_TASK_PROMPTS.md](https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_TASK_PROMPTS.md)
- Full command reference: [CLI Reference](https://github.com/danielcanfly/media2md/blob/main/docs/CLI_REFERENCE.md)
- Release process: [RELEASE_PROCESS.md](https://github.com/danielcanfly/media2md/blob/main/docs/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.

When a login or authenticated session connect is attempted, the CLI warns that platform bot-detection may trigger and offers a no-login path. In non-interactive or agent-driven usage, `auth login` and `auth connect` require explicit `--acknowledge-platform-risk` consent before they proceed.

## Links

- Repository: [danielcanfly/media2md](https://github.com/danielcanfly/media2md)
- PyPI: [media2md](https://pypi.org/project/media2md/)
- First Run Guide: [docs/FIRST_RUN.md](https://github.com/danielcanfly/media2md/blob/main/docs/FIRST_RUN.md)
- Agent Install Guide: [docs/AGENT_INSTALL.md](https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_INSTALL.md)
- Agent Operations Guide: [docs/AGENT_OPERATIONS.md](https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_OPERATIONS.md)
- Agent Auth Selection Policy: [docs/AGENT_AUTH_SELECTION_POLICY.md](https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_AUTH_SELECTION_POLICY.md)
- Agent Decision Map: [docs/AGENT_DECISION_MAP.md](https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_DECISION_MAP.md)
- Agent Task Prompts: [docs/AGENT_TASK_PROMPTS.md](https://github.com/danielcanfly/media2md/blob/main/docs/AGENT_TASK_PROMPTS.md)
- CLI Reference: [docs/CLI_REFERENCE.md](https://github.com/danielcanfly/media2md/blob/main/docs/CLI_REFERENCE.md)
- Release Process: [docs/RELEASE_PROCESS.md](https://github.com/danielcanfly/media2md/blob/main/docs/RELEASE_PROCESS.md)
- Changelog: [CHANGELOG.md](https://github.com/danielcanfly/media2md/blob/main/CHANGELOG.md)
- Contributing: [CONTRIBUTING.md](https://github.com/danielcanfly/media2md/blob/main/CONTRIBUTING.md)
