Media ingestion turns audio, video, and transcript files into structured vault references. ztlctl transcribes audio and video locally using faster-whisper (no data leaves your machine), and parses pre-existing transcript files without any external dependency. Every ingest operation creates a captured reference — the first phase of a two-phase workflow that ends when an agent or user annotates and promotes the reference to annotated status.

Prerequisites¶

Supported formats¶

Ingesting media files¶

Use ztlctl ingest media to ingest an audio or video file. ztlctl loads the whisper model, transcribes the file locally, and creates a captured reference in your vault.

$ ztlctl ingest media PATH [OPTIONS]

Arguments and options:

Example — ingest a podcast recording:

$ ztlctl ingest media recordings/interview-2026-03-21.mp3 \
    --title "Interview: distributed systems patterns" \
    --topic ml/research \
    --tags podcast --tags distributed-systems

Example — preview before writing:

$ ztlctl ingest media lecture.mp4 --dry-run

The --dry-run flag returns a preview with the first 280 characters of the normalized transcript, the resolved title, and the ingest metadata — no files are written.

Ingesting transcripts¶

If you already have a transcript file — from an external transcription service, a video platform, or a manual capture — use ztlctl ingest media with the transcript file directly. No faster-whisper installation is required.

WebVTT file:

$ ztlctl ingest media captions.vtt --title "Conference talk: CRDT internals"

SRT file:

$ ztlctl ingest media subtitles.srt --title "Lecture 4 — consensus protocols"

Plain text transcript:

$ ztlctl ingest media transcript.txt --title "Team meeting notes 2026-03-21"

VTT and SRT files are automatically stripped of timestamps, sequence numbers, and header lines before ingestion. The resulting plain text is stored in the reference body and the normalized text bundle.

The two-phase workflow¶

Every ztlctl ingest media call creates a captured reference — not a finished note. This is intentional: the transcription is raw material that needs human or agent review before it becomes a durable knowledge artifact.

Phase 1: Captured — ztlctl ingest media produces a reference with:

• status: captured in the frontmatter
• The normalized transcript text in the reference body
• A source bundle (written to .ztlctl/bundles/) containing: normalized_text, capture_agent (whisper for audio/video, transcript-parser for transcript files), modalities (e.g. ["audio", "text"]), and the original source_path.

Phase 2: Annotated — An agent or user reviews the captured reference, adds key_points, a summary, and relevant tags, then updates the status to annotated:

$ ztlctl update ZTL-0123 \
    --summary "Key insights from the distributed systems interview" \
    --tags podcast distributed-systems \
    --status annotated

Once annotated, the reference is indexed, tagged, and eligible for reweave link discovery like any other vault content.

Configuration¶

The [ingest.media] section in ztlctl.toml controls the whisper model and transcription behavior:

[ingest.media]
whisper_model = "base"   # model size: tiny, base, small, medium, large-v2
language = null          # ISO language code (e.g. "en", "de"); null = auto-detect
compute_type = "int8"    # quantization: int8 (CPU), float16 (GPU), float32

All config fields (sourced from MediaIngestConfig in config/models.py):

Model size trade-offs:

MCP tool¶

The ingest_media MCP tool mirrors the CLI. Agents use it to ingest media files already accessible on the local filesystem.

Tool name: ingest_media

Side effect: write

Parameters:

Return format:

{
  "id": "REF-0042",
  "path": "references/REF-0042.md",
  "title": "Interview: distributed systems patterns",
  "type": "reference",
  "input_kind": "media",
  "source_kind": "media",
  "modalities": ["audio", "text"],
  "capture_agent": "whisper",
  "source_bundle_version": 1,
  "source_bundle_path": ".ztlctl/bundles/REF-0042/bundle.json"
}

Common errors:

What's next¶

• Concepts — understand references, lifecycle statuses, and source bundles
• Configuration — full ztlctl.toml reference including [ingest.media]
• Agentic workflows — orchestration recipes for capture-and-annotate pipelines