Skip to main content

video2md

An MCP server that turns video/audio files into transcripts and metadata, so an agent (e.g. Claude Code) can write reports in Markdown, LaTeX, HTML, etc.

Tools exposed

  • get_media_info(file_path) — duration, codecs, streams, size.
  • extract_audio(file_path, output_path?) — extract audio to 16kHz mono WAV.
  • transcribe(...) — timestamped transcript. Backends: mlx-whisper (macOS arm64), faster-whisper (cross-platform), openai (cloud). Auto-chunks files > 10 min. Raw Whisper params exposed.
  • list_backends() — available backends.
  • cache_clear() — clear transcript cache.
  • get_report_template(format) — Markdown/LaTeX report skeleton (markdown/md, latex/tex).
  • submit_transcription(...) / get_job_status(job_id) / cancel_job(job_id) — async jobs for long files.

Run with uvx

From a local checkout:

uvx --from . video2md

Without cloning (from GitHub, before/without PyPI publishing):

uvx --from git+https://github.com/<OWNER>/video2md video2md

After publishing to PyPI:

uvx video2md

Claude Code integration

Add to your MCP config (e.g. ~/.claude.json or project .mcp.json).

Local checkout:

{
  "mcpServers": {
    "video2md": {
      "command": "uvx",
      "args": ["--from", "/path/to/video2md", "video2md"]
    }
  }
}

Without cloning (GitHub source):

{
  "mcpServers": {
    "video2md": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/<OWNER>/video2md", "video2md"]
    }
  }
}

Published package:

{
  "mcpServers": {
    "video2md": {
      "command": "uvx",
      "args": ["video2md"]
    }
  }
}

Then ask Claude Code: "Write a summary report from /path/to/video.mp4 in Markdown." The agent will call get_media_info and transcribe, then write the report.

Report skeletons are available via the get_report_template(format) tool (markdown/md or latex/tex) and as files under templates/.

Large files

For files of hundreds of MB (hours of audio), transcribe in chunks to keep memory and context small:

transcribe(path, start_seconds=0, end_seconds=600)
transcribe(path, start_seconds=600, end_seconds=1200)
...

Segment timestamps are returned in absolute seconds. VAD filtering is on by default.

Environment variables

  • VIDEO2MD_BACKEND — auto/mlx-whisper/faster-whisper/whisper-cpp/openai (default: auto).
  • VIDEO2MD_MODEL — default whisper model size (default: base).
  • VIDEO2MD_DEVICE — auto/cpu/cuda/mps (default: auto).
  • VIDEO2MD_COMPUTE_TYPE — compute type (default: auto).
  • VIDEO2MD_WORKERS — parallel workers (default: cpu_count-1).
  • VIDEO2MD_CHUNK_SECONDS — chunk size for auto-chunking (default: 300).
  • VIDEO2MD_CACHE_DIR — cache location.
  • OPENAI_API_KEY — for the openai backend.

Development

uv sync
uv run video2md

Metadata

Release files for video2md 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for video2md 0.2.0
File Size Uploaded Provenance Actions
video2md-0.2.0.tar.gz 17.2 kB Without provenance Details for video2md-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for video2md 0.2.0
File Interpreter ABI Platform Actions
video2md-0.2.0-py3-none-any.whl Python 3 none any Details for video2md-0.2.0-py3-none-any.whl

Total release size: 39.0 kB

Release files / video2md-0.2.0.tar.gz

Download URL video2md-0.2.0.tar.gz
Size 17.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ca0452d237d6e4fb38a82646439c8d3469ae8d473179391410520e1c06f26062
BLAKE2b-256 checksum
How to use checksums
6abdc8ca981ac5cb0e92c99abcf46298d74613a853a41189af664747ad52c876
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / video2md-0.2.0-py3-none-any.whl

Download URL video2md-0.2.0-py3-none-any.whl
Size 21.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a058d483c744809ccdacc6be6a2b9b659d7ad7564c5edf277752eecc4674efb7
BLAKE2b-256 checksum
How to use checksums
0f5002ff87d0216ff5a468826a20c7a21f090511701418583d0271c9423a08df
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for video2md 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page