metadata-generation

Metadata Generation

Generate a structured JSON file of show notes for a podcast episode. The final mixed audio file and the original transcript are sent back to Gemini, which aligns the two and returns a timecoded transcript plus episode metadata.

This is a pipeline producer skill: the orchestrator (podcast-studio) invokes it after the audio mix, passing the run directory via --workspace and the GEMINI_API_KEY in the subprocess environment. It is brand-neutral — episode title, language, and tone are decided upstream by the active show profile and captured in the transcript and audio it receives; this skill only describes what is already there.

Prerequisites

generate_metadata.py imports google-genai + pydub. These live in the orchestrator's uv-managed venv (provisioned at first run, R70) — they are not pip installed into the system Python (PEP 668 refuses that on modern macOS/Debian). The orchestrator creates the venv with uv venv "${XDG_DATA_HOME:-$HOME/.local/share}/podcast-creator/venv" and installs the deps with uv pip install --python "<venv>/bin/python" pydub pyyaml "google-genai>=2.0.1" (see podcast-studio SKILL.md First run + Step 0).

Interpreter (R70). Run this script through the venv interpreter the orchestrator resolved in Step 0 ("$PODCAST_PY" <script>), not bare python3 — the python3 … in the examples is shorthand. (pydub also needs ffmpeg on PATH, a separate system binary.)

Inputs

Read from the run directory passed as --workspace:

• Transcript: {workspace}/data/script.md
• Final audio: {workspace}/audio/final/episode.mp3 (falls back to episode.wav if the mp3 is absent).

Workflow

1. Read inputs — load the transcript and the final mixed audio from the paths above.
2. Measure duration — pydub reads the audio length to produce an MM:SS duration hint for the model.
3. Upload audio — upload the audio file to the Gemini Files API.
4. Generate metadata — call Gemini (gemini-3-flash-preview) via the generate_content API with the uploaded audio plus the transcript text.
5. Save output — write the parsed JSON to {workspace}/data/show_notes.json.

Invocation

python3 "${CLAUDE_SKILL_DIR}/scripts/generate_metadata.py" --workspace <run-dir>

Arguments

Argument	Default	Description
--workspace	workspace	Run directory holding data/ and audio/. The orchestrator passes the active run dir (default ./podcast-output/<slug>/).

Output

A JSON file at {workspace}/data/show_notes.json with this structure:

{
  "show_title": "...",
  "show_duration": "...",
  "two_sentence_summary": "...",
  "date_of_generation": "YYYY-MM-DD",
  "timecoded_transcript": [
    {
      "timecode": "MM:SS",
      "speaker": "...",
      "text": "..."
    }
  ]
}

show_notes.json is the input to cover-image-generation (via its --metadata flag), so the title written here drives the cover.

Error handling

• Missing transcript at {workspace}/data/script.md → prints an error and exits without writing output.
• Missing audio (neither episode.mp3 nor episode.wav) → prints an error and exits.
• Failed upload or API call → reports the error and exits; no partial file is written.
• If the model wraps its reply in a ```json fence, the script strips it before parsing; an unparseable reply is printed raw so the failure is diagnosable.