Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

12.5 KB
Raw Blame
"""
Per-clip content generation (titles, descriptions, tags).

Single source of truth used by CLI, Web UI, and MCP.
"""

import json
import os
from utils.log import warn as log_warn
import subprocess
import sys
import tempfile
import threading
from typing import Optional, Callable

from config.paths import paths
from services import ai_provider
from services.knowledge_base import load_kb_context as kb_load_context, warn_missing_context

# Codex silently truncates long prompts, so it gets a shortened one. The prompts
# here lead with the request precisely so this cut only costs transcript tail.
CODEX_PROMPT_LIMIT = 4000


def _shorten_for_codex(engine: str, prompt: str) -> str:
    return prompt[:CODEX_PROMPT_LIMIT] if engine == "codex" else prompt


CONTENT_KB_FILES = [
    ("05-title-formulas.md", 3000),
    ("06-descriptions-template.md", 2000),
    ("02-voice-and-tone.md", 2000),
    ("01-brand-identity.md", 1000),
    ("12-quick-reference.md", 1500),
]


def load_kb_context(
    files: Optional[list[tuple[str, int]]] = None,
    task: str = "content generation",
) -> str:
    """Load PodStack knowledge base files as inline prompt context."""
    kb_context = kb_load_context(files if files is not None else CONTENT_KB_FILES)
    if not kb_context:
        warn_missing_context(task)
    return kb_context


def _sample_lines(lines: list[str], max_lines: int = 30) -> list[str]:
    """Pick evenly spaced lines so long episodes are represented end to end."""
    if len(lines) <= max_lines:
        return lines
    last = len(lines) - 1
    picked = sorted({round(i * last / (max_lines - 1)) for i in range(max_lines)})
    return [lines[i] for i in picked]


def _parse_content(raw_text: str) -> dict:
    result = {
        "raw_text": raw_text,
        "titles": [],
        "top_pick": "",
        "description": "",
        "tags": "",
        "hashtags": "",
    }
    section = ""
    for line in raw_text.split("\n"):
        stripped = line.strip()
        if not stripped:
            # Keep paragraph breaks in multi-paragraph episode descriptions.
            if section == "description" and result["description"]:
                result["description"] += "\n"
            continue
        upper = stripped.upper()
        if upper.startswith("TITLES"):
            section = "titles"
            continue
        elif upper.startswith("TOP PICK"):
            result["top_pick"] = stripped
            section = ""
            continue
        elif upper.startswith("DESCRIPTION"):
            section = "description"
            continue
        elif upper.startswith("TAGS"):
            section = "tags"
            continue
        elif upper.startswith("HASHTAGS"):
            section = "hashtags"
            continue

        if section == "titles" and stripped[0:1].isdigit() and ". " in stripped[:4]:
            result["titles"].append(stripped)
        elif section == "description":
            result["description"] += stripped + "\n"
        elif section == "tags":
            result["tags"] = stripped
        elif section == "hashtags":
            result["hashtags"] = stripped

    result["description"] = result["description"].strip()
    return result


def _stream_claude_content(
    cli_path: str,
    prompt_file: str,
    project_dir: str,
    timeout: int,
    on_partial: Callable[[dict], None],
) -> Optional[str]:
    """Stream one claude --print run, emitting a parsed partial package as each
    output line completes. Returns the full response text, or None when
    streaming is unavailable so the caller can fall back to the blocking runner.
    """
    args = [
        cli_path, "--print", "--verbose",
        "--output-format", "stream-json", "--include-partial-messages",
        "-p", "-",
    ]
    try:
        prompt_fh = open(prompt_file, encoding="utf-8")
    except Exception:
        return None
    try:
        proc = subprocess.Popen(
            args,
            stdin=prompt_fh,
            stdout=subprocess.PIPE,
            stderr=subprocess.DEVNULL,
            text=True,
            encoding="utf-8",
            errors="replace",
            cwd=project_dir,
        )
    except Exception:
        prompt_fh.close()
        return None

    # readline blocks between deltas, so the timeout is enforced by a watchdog
    # kill rather than an in-loop deadline check.
    watchdog = threading.Timer(timeout, proc.kill)
    watchdog.start()
    text = ""
    final_text = None
    emitted = None
    try:
        for line in proc.stdout:
            line = line.strip()
            if not line.startswith("{"):
                continue
            try:
                event = json.loads(line)
            except Exception:
                continue
            etype = event.get("type")
            if etype == "stream_event":
                delta = (event.get("event") or {}).get("delta") or {}
                if delta.get("type") == "text_delta":
                    chunk = delta.get("text", "")
                    text += chunk
                    if "\n" in chunk:
                        parsed = _parse_content(text)
                        snapshot = json.dumps(parsed, sort_keys=True)
                        if snapshot != emitted:
                            emitted = snapshot
                            on_partial(parsed)
            elif etype == "result":
                final_text = event.get("result") or None
        rc = proc.wait()
    except Exception:
        try:
            proc.kill()
            proc.wait()
        except Exception as exc:
            log_warn("content", "could not stop subprocess", error=exc)
        return None
    finally:
        watchdog.cancel()
        prompt_fh.close()

    out = (final_text or text).strip()
    if rc != 0 or not out:
        return None
    return out


def generate_custom_content(
    instruction: str,
    transcript_segments: list[dict],
    mode: str = "shorts",
    progress_callback: Optional[Callable[[int, str], None]] = None,
) -> Optional[dict]:
    """Run a free-form content request against the AI CLI with KB + transcript context.

    Returns {"text", "engine"} with the raw model output, or None if no AI CLI.
    """
    if not ai_provider.available():
        return None

    kb_context = load_kb_context()
    lines = []
    for seg in transcript_segments:
        sp = seg.get("speaker", "")
        sp_label = f"[{sp}] " if sp else ""
        lines.append(f"{sp_label}{seg.get('text', '').strip()}")
    excerpt = chr(10).join(_sample_lines(lines, max_lines=40))

    # REQUEST first so codex prompt truncation never drops the ask.
    prompt = f"""You are helping create YouTube content for a podcast. Follow the knowledge base voice and rules. Return ONLY the requested output, no preamble.

REQUEST ({'full episode' if mode == 'episode' else 'short clip'}):
{instruction.strip()}

KNOWLEDGE BASE:
{kb_context}

TRANSCRIPT EXCERPT:
{excerpt}"""

    attempted: list[str] = []

    def announce(label: str) -> None:
        if progress_callback:
            progress_callback(30, f"Asking {label}..." if not attempted else f"Retrying with {label}...")
        attempted.append(label)

    result = ai_provider.generate(
        prompt,
        timeout=120,
        on_attempt=announce,
        adapt=_shorten_for_codex,
    )
    if not result.ok:
        print(f"Warning: content generation failed: {result.error}", file=sys.stderr)
        return None
    if progress_callback:
        progress_callback(100, "Done")
    return {"text": result.text, "engine": result.provider}


def generate_clip_content(
    clip: dict,
    transcript_segments: list[dict],
    progress_callback: Optional[Callable[[int, str], None]] = None,
    mode: str = "shorts",
    partial_callback: Optional[Callable[[dict], None]] = None,
) -> Optional[dict]:
    """
    Generate titles, description, tags, and hashtags for a single clip.

    Args:
        clip: dict with title, start_second, end_second, content_type
        transcript_segments: full transcript segments list
        progress_callback: optional (percent, message) callback
        mode: "shorts" (per-clip package) or "episode" (long-form episode package)

    Returns:
        dict with raw_text, titles, description, tags, hashtags, or None if AI unavailable
    """
    providers = ai_provider.status()["providers"]
    if not providers:
        return None

    if progress_callback:
        progress_callback(0, f"Generating content via {providers[0]['label']}...")

    kb_context = load_kb_context(task="title and description generation")

    # Extract transcript text for this clip's time range
    clip_start = clip.get("start_second", 0)
    clip_end = clip.get("end_second", 0)
    clip_transcript = []
    for seg in transcript_segments:
        seg_start = seg.get("start", 0)
        if clip_start - 5 <= seg_start <= clip_end + 5:
            sp = seg.get("speaker", "")
            sp_label = f"[{sp}] " if sp else ""
            clip_transcript.append(f"{sp_label}{seg.get('text', '').strip()}")

    if mode == "episode":
        prompt = f"""Generate a YouTube content package for this full podcast episode. Return ONLY the content below, no preamble.

KNOWLEDGE BASE:
{kb_context}

EPISODE: "{clip.get('title', '')}"

TRANSCRIPT EXCERPT:
{chr(10).join(_sample_lines(clip_transcript))}

Generate exactly this (no other text):

TITLES (8 options, 50-70 chars, keyword-first, follow title spec):
1. [title]
2. [title]
3. [title]
4. [title]
5. [title]
6. [title]
7. [title]
8. [title]
TOP PICK: [number], [why]

DESCRIPTION:
[hook line under 100 chars]
[2-3 short paragraphs: what the episode covers and why it matters]
[guest attribution line]

TAGS:
[comma-separated, 10-15 tags for YouTube]

HASHTAGS:
[3-5 hashtags for description]"""
    else:
        prompt = f"""Generate a YouTube Shorts content package for this clip. Return ONLY the content below, no preamble.

KNOWLEDGE BASE:
{kb_context}

CLIP: "{clip.get('title', '')}"
Duration: {clip_end - clip_start:.0f}s
Content type: {clip.get('content_type', 'unknown')}

TRANSCRIPT EXCERPT:
{chr(10).join(clip_transcript[:30])}

Generate exactly this (no other text):

TITLES (8 options, 40-60 chars, keyword-first, follow title spec):
1. [title]
2. [title]
3. [title]
4. [title]
5. [title]
6. [title]
7. [title]
8. [title]
TOP PICK: [number], [why]

DESCRIPTION:
[hook line under 100 chars]
[guest attribution line]

TAGS:
[comma-separated, 8-12 tags for YouTube]

HASHTAGS:
[5 hashtags for description]"""

    project_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..")

    def usable(text: str) -> bool:
        parsed = _parse_content(text)
        return bool(parsed["titles"] or parsed["description"])

    raw_text = None
    engine_used = ""

    # The Studio renders titles as they arrive. Only the Claude CLI can stream,
    # so it gets first refusal; everything else falls through to the chain.
    if partial_callback is not None:
        cli_path = ai_provider.claude_cli_path()
        if cli_path:
            if progress_callback:
                progress_callback(30, "Asking Claude for titles & descriptions...")
            from utils.prompt_files import write_prompt_file
            prompt_file = write_prompt_file(prompt)
            try:
                raw_text = _stream_claude_content(
                    cli_path=cli_path,
                    prompt_file=prompt_file,
                    project_dir=project_dir,
                    timeout=120,
                    on_partial=partial_callback,
                )
                engine_used = "claude"
            finally:
                try:
                    os.unlink(prompt_file)
                except OSError:
                    pass

    if raw_text is None or not usable(raw_text):
        attempted: list[str] = []

        def announce(label: str) -> None:
            if progress_callback:
                if attempted:
                    progress_callback(0, f"Retrying content generation with {label}...")
                progress_callback(30, f"Asking {label} for titles & descriptions...")
            attempted.append(label)

        attempt = ai_provider.generate(
            prompt,
            timeout=120,
            project_dir=project_dir,
            on_attempt=announce,
            adapt=_shorten_for_codex,
            accept=usable,
        )
        if not attempt.ok:
            return None
        raw_text, engine_used = attempt.text, attempt.provider

    if progress_callback:
        progress_callback(90, "Parsing content...")

    result = _parse_content(raw_text)
    result["engine"] = engine_used

    if progress_callback:
        progress_callback(100, f"Content ready ({len(result['titles'])} titles)")

    return result