Bilibili Subtitle

.venv/
.pixi/
pixi.lock
.cache/
output/
*.egg-info/
**/__pycache__/
.pytest_cache/
*.pyc
*.egg-info/

"""
Bilibili Subtitle Extraction Skill.

Extract subtitles from Bilibili videos with ASR fallback for videos without subtitles.
"""

from __future__ import annotations

__version__ = "0.1.0"
__all__ = [
    "BBDownClient",
    "BBDownError",
    "VideoInfo",
    "SubtitleInfo",
    "detect_subtitles",
    "VideoMetadata",
    "parse_bilibili_ref",
    "VideoRef",
    "SkillError",
    "ErrorLevel",
    "Remediation",
    "PreflightReport",
    "run_preflight",
    "ExecutionResult",
    "SubtitleOutput",
    "ExitCode",
    "build_cli_command",
]

from .bbdown_client import BBDownClient, BBDownError, SubtitleInfo, VideoInfo
from .contract import (
    ExitCode,
    ExecutionResult,
    SubtitleOutput,
    build_cli_command,
)
from .detector import VideoMetadata, detect_subtitles
from .errors import ErrorLevel, Remediation, SkillError
from .preflight import PreflightReport, run_preflight
from .url_parser import VideoRef, parse_bilibili_ref

"""
CLI entry point for bilibili-subtitle skill.

Usage:
    pixi run python -m bilibili_subtitle "BV1234567890"
    pixi run python -m bilibili_subtitle --check
    pixi run python -m bilibili_subtitle "URL" --skip-proofread --skip-summary
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

import re

from .contract import ExitCode, ExecutionResult, SubtitleOutput
from .errors import (
    ASRConfigError,
    BBDownAuthError,
    BBDownDownloadError,
    FFmpegNotFoundError,
    InvalidURLError,
    NoSubtitleError,
    SkillError,
    VideoNotFoundError,
    exit_code_for_error,
)
from .preflight import run_preflight
from .url_parser import parse_bilibili_ref


_WINDOWS_ILLEGAL_RE = re.compile(r'[/\\:*?"<>|]')
_CONTROL_CHAR_RE = re.compile(r'[\x00-\x1f]')


def _sanitize_filename(name: str) -> str:
    """Remove Windows-illegal characters and control chars from a filename."""
    name = _CONTROL_CHAR_RE.sub("", name)
    name = _WINDOWS_ILLEGAL_RE.sub("_", name)
    name = name.strip().strip("_").strip()
    return name or "untitled"


def create_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="bilibili_subtitle",
        description="Extract Bilibili subtitles with ASR fallback",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  %(prog)s "BV1234567890"
  %(prog)s "https://www.bilibili.com/video/BV1234567890"
  %(prog)s "BV1234567890" --skip-proofread --skip-summary
  %(prog)s --check
        """,
    )

    parser.add_argument("url", nargs="?", help="Bilibili URL or BV ID")
    parser.add_argument(
        "-o", "--output-dir", default="./output", help="Output directory"
    )
    parser.add_argument("--output-lang", choices=["zh", "en", "zh+en"], default="zh")
    parser.add_argument(
        "--skip-proofread", action="store_true", help="Skip AI proofreading"
    )
    parser.add_argument(
        "--skip-summary", action="store_true", help="Skip AI summarization"
    )
    parser.add_argument("--cache-dir", default="./.cache", help="Cache directory")
    parser.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
    parser.add_argument("--check", action="store_true", help="Run preflight checks")
    parser.add_argument("--check-json", action="store_true", help="Preflight as JSON")
    parser.add_argument(
        "--skip-auth-check", action="store_true", help="Skip auth check"
    )
    parser.add_argument("--json-output", action="store_true", help="Output as JSON")
    parser.add_argument("--version", action="version", version="%(prog)s 0.2.0")
    return parser


def run_extraction(
    url: str,
    output_dir: Path,
    *,
    output_lang: str = "zh",
    skip_proofread: bool = False,
    skip_summary: bool = False,
    cache_dir: Path = Path("./.cache"),
    verbose: bool = False,
) -> ExecutionResult:
    warnings: list[str] = []
    errors: list[dict] = []

    try:
        ref = parse_bilibili_ref(url)
        video_id = ref.video_id or "unknown"
        canonical_url = ref.canonical_url or ref.input_value
    except Exception:
        raise InvalidURLError(url)

    cache_dir.mkdir(parents=True, exist_ok=True)
    output_dir.mkdir(parents=True, exist_ok=True)

    from .bbdown_client import BBDownClient
    from .segment import Segment
    from .subtitle_loader import load_segments_from_subtitle_file, check_title_relevance

    client = BBDownClient()

    if verbose:
        print(f"[INFO] Processing: {video_id}")
        print(f"[INFO] Output directory: {output_dir}")

    try:
        info = client.get_video_info(canonical_url, cache_dir)
    except Exception as e:
        if "login" in str(e).lower() or "auth" in str(e).lower():
            raise BBDownAuthError(str(e))
        if "not found" in str(e).lower() or "不存在" in str(e).lower():
            raise VideoNotFoundError(video_id or "unknown")
        raise BBDownDownloadError(canonical_url, str(e))

    if verbose:
        print(f"[INFO] Title: {info.title}")
        print(f"[INFO] Has subtitle: {info.subtitle_info.has_subtitle}")

    segments: list[Segment] = []

    if info.subtitle_files:
        max_crosstalk_retries = 2
        for attempt in range(max_crosstalk_retries + 1):
            sub_file = info.subtitle_files[0]
            if verbose:
                print(f"[INFO] Loading subtitle: {sub_file.name}")
            load_result = load_segments_from_subtitle_file(sub_file, title=info.title)
            segments = load_result.segments

            if load_result.relevant:
                break

            # Crosstalk detected — subtitle may belong to a different video
            if attempt < max_crosstalk_retries:
                warnings.append(
                    f"Crosstalk suspected (attempt {attempt + 1}), re-downloading..."
                )
                if verbose:
                    print(f"[WARN] Subtitle may not match title, retrying ({attempt + 1}/{max_crosstalk_retries})")
                # Delete stale file and re-fetch
                sub_file.unlink(missing_ok=True)
                try:
                    info = client.get_video_info(canonical_url, cache_dir)
                except Exception:
                    break  # Can't retry, use what we have
                if not info.subtitle_files:
                    break
            else:
                warnings.append(
                    "Subtitle content may not match video title (crosstalk); proceeding anyway"
                )
    elif not info.subtitle_info.has_subtitle:
        warnings.append("No subtitles found, attempting ASR transcription")

        import shutil

        if not shutil.which("ffmpeg"):
            raise FFmpegNotFoundError()

        from .audio_extractor import extract_audio
        from .agents.transcribe_agent import TranscribeAgent

        try:
            audio_path = extract_audio(canonical_url, cache_dir)
            if verbose:
                print(f"[INFO] Audio extracted: {audio_path}")

            transcriber = TranscribeAgent(mode="qwen")
            result = transcriber.transcribe(str(audio_path))
            segments = result.segments

            if audio_path.exists():
                audio_path.unlink()
        except Exception as e:
            if "DASHSCOPE_API_KEY" in str(e):
                raise ASRConfigError()
            raise

    if not segments:
        raise NoSubtitleError(video_id)

    if not skip_proofread:
        import os

        if not os.environ.get("ANTHROPIC_API_KEY"):
            warnings.append("ANTHROPIC_API_KEY not set, skipping proofreading")
        else:
            if verbose:
                print("[INFO] Proofreading...")
            from .agents.proofread_agent import ProofreadAgent

            proofer = ProofreadAgent()
            try:
                segments = proofer.proofread_segments(segments)
            except Exception as e:
                warnings.append(f"Proofreading failed: {e}")

    from .renderers.srt import render_srt
    from .renderers.vtt import render_vtt
    from .renderers.markdown import render_transcript_markdown

    srt_content = render_srt(segments)
    vtt_content = render_vtt(segments)
    md_content = render_transcript_markdown(segments, title=info.title)

    lang_suffix = "" if output_lang == "zh" else f".{output_lang}"
    safe_title = _sanitize_filename(info.title or video_id)
    srt_path = output_dir / f"{safe_title}{lang_suffix}.srt"
    vtt_path = output_dir / f"{safe_title}{lang_suffix}.vtt"
    md_path = output_dir / f"{safe_title}.transcript.md"

    srt_path.write_text(srt_content, encoding="utf-8")
    vtt_path.write_text(vtt_content, encoding="utf-8")
    md_path.write_text(md_content, encoding="utf-8")

    if verbose:
        print(f"[INFO] Generated: {srt_path.name}")
        print(f"[INFO] Generated: {md_path.name}")

    summary_json_path = None
    summary_md_path = None

    if not skip_summary:
        import os

        if not os.environ.get("ANTHROPIC_API_KEY"):
            warnings.append("ANTHROPIC_API_KEY not set, skipping summarization")
        else:
            if verbose:
                print("[INFO] Summarizing...")
            from .agents.summarize_agent import SummarizeAgent

            summarizer = SummarizeAgent()
            try:
                result = summarizer.summarize(segments, title=info.title)
                summary_json_path = output_dir / f"{safe_title}.summary.json"
                summary_md_path = output_dir / f"{safe_title}.summary.md"
                summary_json_path.write_text(
                    json.dumps(result.summary, ensure_ascii=False, indent=2),
                    encoding="utf-8",
                )
                summary_md_path.write_text(result.raw_text or "", encoding="utf-8")
            except Exception as e:
                warnings.append(f"Summarization failed: {e}")

    output = SubtitleOutput(
        video_id=video_id,
        title=info.title,
        transcript_md=md_path,
        srt_file=srt_path,
        vtt_file=vtt_path,
        summary_json=summary_json_path,
        summary_md=summary_md_path,
    )

    return ExecutionResult(
        exit_code=ExitCode.SUCCESS if not errors else ExitCode.PARTIAL_SUCCESS,
        output=output,
        errors=errors,
        warnings=warnings,
        metadata={"url": canonical_url},
    )


def main() -> int:
    parser = create_parser()
    args = parser.parse_args()

    if args.check or args.check_json:
        report = run_preflight(include_auth=not args.skip_auth_check)
        if args.check_json:
            print(report.to_json())
        else:
            report.print_report()
        return 0 if report.can_proceed else 1

    if not args.url:
        parser.error("URL is required (unless using --check)")

    output_dir = Path(args.output_dir)
    cache_dir = Path(args.cache_dir)

    try:
        result = run_extraction(
            args.url,
            output_dir,
            output_lang=args.output_lang,
            skip_proofread=args.skip_proofread,
            skip_summary=args.skip_summary,
            cache_dir=cache_dir,
            verbose=args.verbose,
        )

        if args.json_output:
            print(result.to_json())
        else:
            if result.output:
                print(
                    f"✅ {result.output.video_id}: {result.output.title or 'No title'}"
                )
                if result.output.transcript_md:
                    print(f"   Transcript: {result.output.transcript_md}")
            for w in result.warnings:
                print(f"⚠️  {w}")

        return result.exit_code.value

    except SkillError as e:
        if args.json_output:
            print(
                json.dumps(
                    {
                        "exit_code": exit_code_for_error(e),
                        "error": e.to_json(),
                    },
                    indent=2,
                )
            )
        else:
            print(str(e), file=sys.stderr)
        return exit_code_for_error(e)

    except Exception as e:
        if args.json_output:
            print(
                json.dumps(
                    {
                        "exit_code": 1,
                        "error": {"code": "E999", "message": str(e)},
                    },
                    indent=2,
                )
            )
        else:
            print(f"❌ Unexpected error: {e}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    sys.exit(main())

from __future__ import annotations

import json
import os
from dataclasses import dataclass
from typing import Any, Literal

from ..segment import Segment


Mode = Literal["noop", "anthropic"]


def diff_segments(before: list[Segment], after: list[Segment]) -> list[dict[str, Any]]:
    if len(before) != len(after):
        raise ValueError("diff_segments requires equal-length segment lists.")

    changes: list[dict[str, Any]] = []
    for i, (b, a) in enumerate(zip(before, after, strict=True)):
        if (b.start_ms, b.end_ms) != (a.start_ms, a.end_ms):
            raise ValueError("diff_segments requires timestamps to be unchanged.")
        if b.text != a.text:
            changes.append({"index": i, "before": b.text, "after": a.text})
    return changes


def _extract_json_array(text: str) -> Any:
    text = text.strip()
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        pass

    # Tolerate code fences / extra prose.
    start = text.find("[")
    end = text.rfind("]")
    if start == -1 or end == -1 or end <= start:
        raise ValueError("Model output did not contain a JSON array.")
    return json.loads(text[start : end + 1])


@dataclass(frozen=True, slots=True)
class ProofreadResult:
    segments: list[Segment]
    changes: list[dict[str, Any]]


class ProofreadAgent:
    def __init__(
        self,
        *,
        mode: Mode = "anthropic",
        model: str = "claude-3-5-sonnet-latest",
        api_key: str | None = None,
    ) -> None:
        self._mode = mode
        self._model = model
        self._api_key = api_key

    def proofread_segments(self, segments: list[Segment]) -> list[Segment]:
        return self.proofread(segments).segments

    def proofread(self, segments: list[Segment]) -> ProofreadResult:
        if self._mode == "noop":
            return ProofreadResult(segments=segments, changes=[])

        api_key = self._api_key or os.environ.get("ANTHROPIC_API_KEY")
        if not api_key:
            raise RuntimeError("Missing ANTHROPIC_API_KEY (or pass api_key=...).")

        try:
            from anthropic import Anthropic  # type: ignore[import-not-found]
        except Exception as e:  # pragma: no cover
            raise RuntimeError("anthropic package is required for proofreading. Install: pip install anthropic") from e

        client = Anthropic(api_key=api_key)

        payload = [
            {"index": i, "start_ms": s.start_ms, "end_ms": s.end_ms, "text": s.text}
            for i, s in enumerate(segments)
        ]

        system = (
            "You are a subtitle proofreader for Chinese content.\n"
            "Rules:\n"
            "- Do NOT change start_ms/end_ms.\n"
            "- Only fix typos, punctuation, spacing, and obvious ASR errors.\n"
            "- Keep proper nouns consistent.\n"
            "- Do NOT add or remove segments.\n"
            "- Output ONLY a JSON array, each item: {\"index\": number, \"text\": string}.\n"
        )

        user = (
            "Proofread these subtitle segments. Return corrected text per index as JSON array.\n\n"
            f"{json.dumps(payload, ensure_ascii=False)}"
        )

        msg = client.messages.create(
            model=self._model,
            max_tokens=4096,
            system=system,
            messages=[{"role": "user", "content": user}],
        )

        content = ""
        for block in msg.content:
            if getattr(block, "type", None) == "text":
                content += block.text

        items = _extract_json_array(content)
        if not isinstance(items, list):
            raise ValueError("Model output was not a JSON array.")

        corrected_text_by_index: dict[int, str] = {}
        for item in items:
            if not isinstance(item, dict):
                continue
            idx = item.get("index")
            text = item.get("text")
            if isinstance(idx, int) and isinstance(text, str):
                corrected_text_by_index[idx] = text

        out: list[Segment] = []
        for i, seg in enumerate(segments):
            text = corrected_text_by_index.get(i, seg.text)
            out.append(Segment(start_ms=seg.start_ms, end_ms=seg.end_ms, text=text))

        return ProofreadResult(segments=out, changes=diff_segments(segments, out))

from __future__ import annotations

import json
import os
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Literal

from ..segment import Segment


Mode = Literal["noop", "anthropic"]


def default_summary() -> dict[str, Any]:
    return {
        "key_points": [],
        "outline": [],
        "entities": [],
        "timestamps": [],
    }


def load_summary_schema(schema_path: str | Path = Path("schemas/summary_schema.json")) -> dict[str, Any]:
    data = Path(schema_path).read_text(encoding="utf-8")
    return json.loads(data)


@dataclass(frozen=True, slots=True)
class SummarizeResult:
    summary: dict[str, Any]
    raw_text: str | None = None


class SummarizeAgent:
    def __init__(
        self,
        *,
        mode: Mode = "anthropic",
        model: str = "claude-3-5-sonnet-latest",
        api_key: str | None = None,
    ) -> None:
        self._mode = mode
        self._model = model
        self._api_key = api_key

    def summarize(self, segments: list[Segment], *, title: str | None = None) -> SummarizeResult:
        if self._mode == "noop":
            return SummarizeResult(summary=default_summary(), raw_text=None)

        api_key = self._api_key or os.environ.get("ANTHROPIC_API_KEY")
        if not api_key:
            raise RuntimeError("Missing ANTHROPIC_API_KEY (or pass api_key=...).")

        try:
            from anthropic import Anthropic  # type: ignore[import-not-found]
        except Exception as e:  # pragma: no cover
            raise RuntimeError("anthropic package is required for summarization. Install: pip install anthropic") from e

        client = Anthropic(api_key=api_key)
        schema = load_summary_schema()

        transcript = [
            {"index": i, "start_ms": s.start_ms, "end_ms": s.end_ms, "text": s.text}
            for i, s in enumerate(segments)
        ]

        system = (
            "You summarize transcripts into a structured JSON object.\n"
            "Return ONLY valid JSON matching the provided JSON Schema.\n"
            "Include timestamp references using {start_ms,end_ms,segment_indices[]}.\n"
        )
        user = {
            "title": title,
            "schema": schema,
            "transcript": transcript,
        }

        msg = client.messages.create(
            model=self._model,
            max_tokens=4096,
            system=system,
            messages=[{"role": "user", "content": json.dumps(user, ensure_ascii=False)}],
        )

        content = ""
        for block in msg.content:
            if getattr(block, "type", None) == "text":
                content += block.text

        text = content.strip()
        try:
            summary = json.loads(text)
        except json.JSONDecodeError:
            start = text.find("{")
            end = text.rfind("}")
            if start == -1 or end == -1 or end <= start:
                raise ValueError("Model output did not contain a JSON object.")
            summary = json.loads(text[start : end + 1])

        if not isinstance(summary, dict):
            raise ValueError("Model output was not a JSON object.")

        return SummarizeResult(summary=summary, raw_text=text)

from __future__ import annotations

import os
import subprocess
import tempfile
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Literal

from ..segment import Segment

Mode = Literal["noop", "openai", "qwen"]


@dataclass(frozen=True, slots=True)
class TranscribeResult:
    segments: list[Segment]
    raw: Any | None = None


class TranscribeAgent:
    def __init__(
        self,
        *,
        mode: Mode = "qwen",
        model: str = "qwen3-asr-flash",
        api_key: str | None = None,
    ) -> None:
        self._mode = mode
        self._model = model
        self._api_key = api_key

    def transcribe(self, audio_path: str) -> TranscribeResult:
        if self._mode == "noop":
            return TranscribeResult(segments=[], raw=None)
        elif self._mode == "qwen":
            return self._transcribe_qwen(audio_path)
        else:
            return self._transcribe_openai(audio_path)

    def _transcribe_qwen(self, audio_path: str) -> TranscribeResult:
        import dashscope

        api_key = self._api_key or os.environ.get("DASHSCOPE_API_KEY")
        if not api_key:
            raise RuntimeError("Missing DASHSCOPE_API_KEY")

        dashscope.api_key = api_key

        # Convert to wav if needed
        wav_path = self._ensure_wav(audio_path)

        try:
            text = self._call_asr(wav_path)
        finally:
            if wav_path != audio_path and Path(wav_path).exists():
                Path(wav_path).unlink()

        # Create a single segment for the audio
        if text.strip():
            from ..chunker import probe_duration_ms
            duration_ms = probe_duration_ms(audio_path)
            segments = [Segment(start_ms=0, end_ms=duration_ms, text=text.strip())]
        else:
            segments = []

        return TranscribeResult(segments=segments, raw={"text": text})

    def _ensure_wav(self, audio_path: str) -> str:
        """Convert audio to wav format if needed."""
        path = Path(audio_path)
        if path.suffix.lower() == ".wav":
            return audio_path

        wav_path = path.with_suffix(".wav")
        cmd = [
            "ffmpeg", "-y", "-v", "error",
            "-i", str(path),
            "-ar", "16000", "-ac", "1",
            str(wav_path)
        ]
        subprocess.run(cmd, check=True)
        return str(wav_path)

    def _call_asr(self, wav_path: str) -> str:
        """Call Qwen ASR API."""
        from dashscope import MultiModalConversation

        messages = [
            {"role": "system", "content": [{"text": ""}]},
            {"role": "user", "content": [{"audio": wav_path}]}
        ]

        response = MultiModalConversation.call(
            model=self._model,
            messages=messages,
            result_format="message",
            asr_options={"language": "zh", "enable_itn": True}
        )

        if response.status_code != 200:
            raise RuntimeError(f"ASR failed: {response.message}")

        choice = response.output.choices[0]
        content = choice.message.content[0]
        return content.get("text", "")

    def _transcribe_openai(self, audio_path: str) -> TranscribeResult:
        api_key = self._api_key or os.environ.get("OPENAI_API_KEY")
        if not api_key:
            raise RuntimeError("Missing OPENAI_API_KEY")

        from openai import OpenAI

        client = OpenAI(api_key=api_key)
        with open(audio_path, "rb") as f:
            resp = client.audio.transcriptions.create(
                model="whisper-1",
                file=f,
                response_format="verbose_json",
                timestamp_granularities=["segment"],
            )

        segments: list[Segment] = []
        for seg in getattr(resp, "segments", []) or []:
            start_s = getattr(seg, "start", None)
            end_s = getattr(seg, "end", None)
            text = getattr(seg, "text", "") or ""
            if start_s is None or end_s is None:
                continue
            segments.append(Segment(
                start_ms=int(round(float(start_s) * 1000)),
                end_ms=int(round(float(end_s) * 1000)),
                text=" ".join(str(text).split()),
            ))

        return TranscribeResult(segments=segments, raw=resp)

from __future__ import annotations

import json
import os
from dataclasses import dataclass
from typing import Any, Literal

from ..segment import Segment


Mode = Literal["noop", "anthropic"]


def _extract_json_array(text: str) -> Any:
    text = text.strip()
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        pass
    start = text.find("[")
    end = text.rfind("]")
    if start == -1 or end == -1 or end <= start:
        raise ValueError("Model output did not contain a JSON array.")
    return json.loads(text[start : end + 1])


@dataclass(frozen=True, slots=True)
class TranslateResult:
    segments: list[Segment]
    raw_text: str | None = None


class TranslateAgent:
    def __init__(
        self,
        *,
        mode: Mode = "anthropic",
        model: str = "claude-3-5-sonnet-latest",
        api_key: str | None = None,
    ) -> None:
        self._mode = mode
        self._model = model
        self._api_key = api_key

    def translate_segments(self, segments: list[Segment]) -> list[Segment]:
        return self.translate(segments).segments

    def translate(self, segments: list[Segment]) -> TranslateResult:
        if self._mode == "noop":
            return TranslateResult(segments=segments, raw_text=None)

        api_key = self._api_key or os.environ.get("ANTHROPIC_API_KEY")
        if not api_key:
            raise RuntimeError("Missing ANTHROPIC_API_KEY (or pass api_key=...).")

        try:
            from anthropic import Anthropic  # type: ignore[import-not-found]
        except Exception as e:  # pragma: no cover
            raise RuntimeError("anthropic package is required for translation. Install: pip install anthropic") from e

        client = Anthropic(api_key=api_key)

        payload = [
            {"index": i, "start_ms": s.start_ms, "end_ms": s.end_ms, "text": s.text}
            for i, s in enumerate(segments)
        ]

        system = (
            "Translate Chinese subtitles to natural English.\n"
            "Rules:\n"
            "- Do NOT change timestamps.\n"
            "- Do NOT add or remove segments.\n"
            "- Output ONLY a JSON array: {\"index\": number, \"text\": string}.\n"
        )
        user = "Translate these segments to English:\n\n" + json.dumps(payload, ensure_ascii=False)

        msg = client.messages.create(
            model=self._model,
            max_tokens=4096,
            system=system,
            messages=[{"role": "user", "content": user}],
        )

        content = ""
        for block in msg.content:
            if getattr(block, "type", None) == "text":
                content += block.text

        items = _extract_json_array(content)
        if not isinstance(items, list):
            raise ValueError("Model output was not a JSON array.")

        translated_by_index: dict[int, str] = {}
        for item in items:
            if not isinstance(item, dict):
                continue
            idx = item.get("index")
            text = item.get("text")
            if isinstance(idx, int) and isinstance(text, str):
                translated_by_index[idx] = text

        out: list[Segment] = []
        for i, seg in enumerate(segments):
            text = translated_by_index.get(i, seg.text)
            out.append(Segment(start_ms=seg.start_ms, end_ms=seg.end_ms, text=text))

        return TranslateResult(segments=out, raw_text=content.strip())

from __future__ import annotations

from pathlib import Path

from .bbdown_client import BBDownClient
from .url_parser import parse_bilibili_ref


def extract_audio(
    url_or_id: str,
    output_dir: str | Path,
) -> Path:
    ref = parse_bilibili_ref(url_or_id)
    url = ref.canonical_url or ref.input_value
    output_dir = Path(output_dir)

    client = BBDownClient()
    return client.download_audio(url, output_dir)

from __future__ import annotations

import logging
import re
import shutil
import subprocess
import time
from dataclasses import dataclass
from pathlib import Path

logger = logging.getLogger(__name__)

# --- Compiled regexes for subtitle info extraction (Fix 5) ---
_SUBTITLE_LINE_RE = re.compile(
    r"下载字幕|download.*subtitle|saving subtitle|字幕下载", re.IGNORECASE
)
_AI_MARKER_RE = re.compile(
    r"ai[_\-]|AI识别|auto.?generated|asr|自动识别", re.IGNORECASE
)
_LANG_RE = re.compile(
    r"\b(zh-hans|zh-hant|zh|en|ja|ko)\b", re.IGNORECASE
)

_LANG_NORMALIZE: dict[str, str] = {
    "zh-hans": "zh",
    "zh-hant": "zh-hant",
}

# Errors that should NOT be retried
_FATAL_PATTERNS = re.compile(
    r"login|auth|cookie|not found|不存在|404|权限", re.IGNORECASE
)


@dataclass(frozen=True, slots=True)
class SubtitleInfo:
    has_subtitle: bool
    has_ai_subtitle: bool
    languages: list[str]


@dataclass(frozen=True, slots=True)
class VideoInfo:
    video_id: str
    title: str | None
    subtitle_info: SubtitleInfo
    subtitle_files: list[Path]


class BBDownError(Exception):
    pass


class BBDownClient:
    def __init__(self) -> None:
        self._bbdown = self._find_bbdown()

    def _find_bbdown(self) -> str:
        path = shutil.which("BBDown")
        if path:
            return path
        local = Path(__file__).parent.parent / "BBDown"
        if local.exists():
            return str(local)
        raise BBDownError(
            "BBDown not found. Download from: https://github.com/nilaoda/BBDown/releases"
        )

    def _base_args(self) -> list[str]:
        return [self._bbdown]

    def _run(
        self,
        args: list[str],
        *,
        check: bool = True,
        max_retries: int = 3,
        retry_delay: float = 1.0,
        timeout: int = 120,
    ) -> subprocess.CompletedProcess[str]:
        """Run BBDown with retry + timeout (Fix 1)."""
        last_exc: Exception | None = None

        for attempt in range(max_retries):
            try:
                result = subprocess.run(
                    args,
                    capture_output=True,
                    text=True,
                    check=False,
                    timeout=timeout,
                )
                # If check requested and non-zero, see if it's fatal
                if check and result.returncode != 0:
                    combined = result.stdout + result.stderr
                    if _FATAL_PATTERNS.search(combined):
                        raise BBDownError(f"BBDown failed (non-retryable): {result.stderr}")
                    # Retryable error
                    last_exc = BBDownError(f"BBDown failed (rc={result.returncode}): {result.stderr}")
                    logger.warning(
                        "BBDown attempt %d/%d failed (rc=%d), retrying in %.1fs",
                        attempt + 1, max_retries, result.returncode, retry_delay * (2 ** attempt),
                    )
                    time.sleep(retry_delay * (2 ** attempt))
                    continue
                return result

            except subprocess.TimeoutExpired:
                last_exc = BBDownError(f"BBDown timed out after {timeout}s")
                logger.warning(
                    "BBDown attempt %d/%d timed out, retrying in %.1fs",
                    attempt + 1, max_retries, retry_delay * (2 ** attempt),
                )
                time.sleep(retry_delay * (2 ** attempt))
                continue

            except BBDownError:
                raise

            except Exception as e:
                raise BBDownError(f"BBDown failed: {e}") from e

        raise last_exc or BBDownError("BBDown failed after retries")

    def get_video_info(
        self, url: str, work_dir: Path, *, lang: str | None = "zh-Hans"
    ) -> VideoInfo:
        """Download subtitles and return video info (Fix 4, 7)."""
        work_dir.mkdir(parents=True, exist_ok=True)
        video_id = self._extract_video_id(url)

        existing_files = set(work_dir.glob(f"{video_id}*.srt")) | set(
            work_dir.glob(f"{video_id}*.vtt")
        )

        args = self._base_args() + [
            "--sub-only",
            "--skip-ai",
            "false",
            "-F",
            video_id,
            "--work-dir",
            str(work_dir),
        ]
        if lang is not None:
            args += ["--select-lang", lang]
        args.append(url)

        result = self._run(args, check=False)
        output = result.stdout + result.stderr

        new_files = sorted(
            (set(work_dir.glob(f"{video_id}*.srt")) | set(work_dir.glob(f"{video_id}*.vtt")))
            - existing_files
        )

        # Fix 7: raise on non-zero exit when no files were produced
        if result.returncode != 0 and not new_files:
            logger.error("BBDown exited %d with no subtitle files", result.returncode)
            raise BBDownError(
                f"BBDown failed (rc={result.returncode}): {output[-500:]}"
            )

        title = self._extract_title(output)
        subtitle_info = self._extract_subtitle_info(output)
        return VideoInfo(
            video_id=video_id,
            title=title,
            subtitle_info=subtitle_info,
            subtitle_files=new_files,
        )

    def _extract_video_id(self, url: str) -> str:
        bv_match = re.search(r"(BV[0-9A-Za-z]{10})", url)
        if bv_match:
            return bv_match.group(1)
        av_match = re.search(r"av(\d+)", url, re.IGNORECASE)
        if av_match:
            return f"av{av_match.group(1)}"
        return "unknown"

    def _extract_title(self, output: str) -> str | None:
        for line in output.splitlines():
            cleaned = re.sub(r"^\[[^\]]+\]\s*-\s*", "", line).strip()
            match = re.search(r"(?:视频标题|标题|Title)\s*[:：]\s*(.+)", cleaned)
            if match:
                return match.group(1).strip()
        return None

    def _extract_subtitle_info(self, output: str) -> SubtitleInfo:
        """Parse BBDown output for subtitle metadata (Fix 5)."""
        has_subtitle = False
        has_ai_subtitle = False
        languages: list[str] = []

        for line in output.splitlines():
            if not _SUBTITLE_LINE_RE.search(line):
                continue
            has_subtitle = True
            if _AI_MARKER_RE.search(line):
                has_ai_subtitle = True
            lang_match = _LANG_RE.search(line)
            if lang_match:
                raw = lang_match.group(1).lower()
                normalized = _LANG_NORMALIZE.get(raw, raw)
                if normalized not in languages:
                    languages.append(normalized)

        return SubtitleInfo(
            has_subtitle=has_subtitle,
            has_ai_subtitle=has_ai_subtitle,
            languages=languages,
        )

    def download_audio(self, url: str, work_dir: Path) -> Path:
        work_dir.mkdir(parents=True, exist_ok=True)
        video_id = self._extract_video_id(url)

        args = self._base_args() + [
            "--audio-only",
            "-F",
            video_id,
            "--work-dir",
            str(work_dir),
            url,
        ]
        self._run(args)

        audio_files = list(work_dir.glob(f"{video_id}.*"))
        audio_exts = (".m4a", ".aac", ".mp3", ".flac", ".wav")
        for f in audio_files:
            if f.suffix.lower() in audio_exts:
                return f

        all_audio = [f for f in work_dir.iterdir() if f.suffix.lower() in audio_exts]
        if all_audio:
            return sorted(all_audio, key=lambda p: p.stat().st_mtime, reverse=True)[0]

        raise BBDownError("Audio download produced no output.")

from __future__ import annotations

import json
import re
from dataclasses import asdict, dataclass
from pathlib import Path
from typing import Any

from .segment import Segment


def _safe_name(value: str) -> str:
    value = value.strip() or "unknown"
    return re.sub(r"[^A-Za-z0-9._-]+", "_", value)


@dataclass(frozen=True, slots=True)
class CachedSegments:
    video_id: str
    segments: list[Segment]


class Cache:
    def __init__(self, cache_dir: str | Path) -> None:
        self._dir = Path(cache_dir)
        self._dir.mkdir(parents=True, exist_ok=True)

    def _path(self, video_id: str, name: str) -> Path:
        return self._dir / f"{_safe_name(video_id)}.{_safe_name(name)}.json"

    def load_segments(self, video_id: str, name: str) -> list[Segment] | None:
        path = self._path(video_id, name)
        if not path.exists():
            return None
        data = json.loads(path.read_text(encoding="utf-8"))
        if not isinstance(data, list):
            return None
        out: list[Segment] = []
        for item in data:
            if not isinstance(item, dict):
                continue
            out.append(Segment(start_ms=item["start_ms"], end_ms=item["end_ms"], text=item["text"]))
        return out

    def save_segments(self, video_id: str, name: str, segments: list[Segment]) -> Path:
        path = self._path(video_id, name)
        data: list[dict[str, Any]] = [asdict(s) for s in segments]
        path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
        return path

from __future__ import annotations

import json
import subprocess
from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True, slots=True)
class AudioChunk:
    start_ms: int
    end_ms: int
    path: Path


def probe_duration_ms(input_path: str | Path) -> int:
    input_path = Path(input_path)
    cmd = [
        "ffprobe",
        "-v",
        "error",
        "-show_entries",
        "format=duration",
        "-of",
        "json",
        str(input_path),
    ]
    try:
        out = subprocess.check_output(cmd, text=True)
    except FileNotFoundError as e:  # pragma: no cover
        raise RuntimeError("ffprobe not found. Install ffmpeg.") from e
    data = json.loads(out)
    dur = float(data["format"]["duration"])
    return int(round(dur * 1000))


def chunk_audio_ffmpeg(
    input_path: str | Path,
    output_dir: str | Path,
    *,
    chunk_seconds: int = 60,
    overlap_seconds: int = 2,
) -> list[AudioChunk]:
    input_path = Path(input_path)
    output_dir = Path(output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    duration_ms = probe_duration_ms(input_path)
    chunk_ms = chunk_seconds * 1000
    overlap_ms = overlap_seconds * 1000
    if chunk_ms <= 0:
        raise ValueError("chunk_seconds must be > 0.")
    if overlap_ms < 0 or overlap_ms >= chunk_ms:
        raise ValueError("overlap_seconds must be >= 0 and < chunk_seconds.")

    step_ms = chunk_ms - overlap_ms
    chunks: list[AudioChunk] = []
    start_ms = 0
    idx = 0
    while start_ms < duration_ms:
        end_ms = min(duration_ms, start_ms + chunk_ms)
        out_path = output_dir / f"chunk_{idx:04d}_{start_ms}_{end_ms}{input_path.suffix}"
        cmd = [
            "ffmpeg",
            "-y",
            "-v",
            "error",
            "-ss",
            f"{start_ms / 1000:.3f}",
            "-t",
            f"{(end_ms - start_ms) / 1000:.3f}",
            "-i",
            str(input_path),
            "-c",
            "copy",
            str(out_path),
        ]
        try:
            subprocess.check_call(cmd)
        except FileNotFoundError as e:  # pragma: no cover
            raise RuntimeError("ffmpeg not found. Install ffmpeg.") from e

        chunks.append(AudioChunk(start_ms=start_ms, end_ms=end_ms, path=out_path))
        idx += 1
        start_ms += step_ms

    return chunks

"""
Sub-skill invocation contract.

Standardized interface for parent skills to invoke this skill.
"""

from __future__ import annotations

import json
from dataclasses import dataclass, field
from enum import Enum
from pathlib import Path
from typing import Any, Literal


class ExitCode(Enum):
    SUCCESS = 0
    FATAL_ERROR = 1
    RECOVERABLE_ERROR = 2
    PARTIAL_SUCCESS = 3


@dataclass
class SubtitleOutput:
    video_id: str
    title: str | None = None
    transcript_md: Path | None = None
    srt_file: Path | None = None
    vtt_file: Path | None = None
    summary_json: Path | None = None
    summary_md: Path | None = None

    def to_dict(self) -> dict[str, Any]:
        return {
            "video_id": self.video_id,
            "title": self.title,
            "files": {
                "transcript": str(self.transcript_md) if self.transcript_md else None,
                "srt": str(self.srt_file) if self.srt_file else None,
                "vtt": str(self.vtt_file) if self.vtt_file else None,
                "summary_json": str(self.summary_json) if self.summary_json else None,
                "summary_md": str(self.summary_md) if self.summary_md else None,
            },
        }


@dataclass
class ExecutionResult:
    exit_code: ExitCode
    output: SubtitleOutput | None = None
    errors: list[dict[str, Any]] = field(default_factory=list)
    warnings: list[str] = field(default_factory=list)
    metadata: dict[str, Any] = field(default_factory=dict)

    @property
    def success(self) -> bool:
        return self.exit_code in (ExitCode.SUCCESS, ExitCode.PARTIAL_SUCCESS)

    def to_dict(self) -> dict[str, Any]:
        return {
            "exit_code": self.exit_code.value,
            "success": self.success,
            "output": self.output.to_dict() if self.output else None,
            "errors": self.errors,
            "warnings": self.warnings,
            "metadata": self.metadata,
        }

    def to_json(self) -> str:
        return json.dumps(self.to_dict(), indent=2, ensure_ascii=False)

    def write_manifest(self, path: Path) -> None:
        path.write_text(self.to_json(), encoding="utf-8")


def build_cli_command(
    url_or_id: str,
    output_dir: str | Path,
    *,
    skip_proofread: bool = False,
    skip_summary: bool = True,
    output_lang: Literal["zh", "en", "zh+en"] = "zh",
    cache_dir: str | Path | None = None,
    verbose: bool = False,
) -> list[str]:
    cmd = [
        "pixi",
        "run",
        "python",
        "-m",
        "bilibili_subtitle",
        url_or_id,
        "-o",
        str(output_dir),
        "--output-lang",
        output_lang,
    ]
    if skip_proofread:
        cmd.append("--skip-proofread")
    if skip_summary:
        cmd.append("--skip-summary")
    if cache_dir:
        cmd.extend(["--cache-dir", str(cache_dir)])
    if verbose:
        cmd.append("-v")
    return cmd


def parse_execution_result(
    output_dir: Path, exit_code: int, stderr: str = ""
) -> ExecutionResult:
    errors: list[dict[str, Any]] = []
    warnings: list[str] = []

    video_id = _extract_video_id_from_dir(output_dir)

    srt_files = list(output_dir.glob("*.srt"))
    vtt_files = list(output_dir.glob("*.vtt"))
    transcript_files = list(output_dir.glob("*.transcript.md"))
    summary_json_files = list(output_dir.glob("*.summary.json"))
    summary_md_files = list(output_dir.glob("*.summary.md"))

    has_transcript = bool(transcript_files)
    has_subtitle = bool(srt_files)

    result_exit_code = (
        ExitCode(exit_code) if exit_code in (0, 1, 2, 3) else ExitCode.FATAL_ERROR
    )

    if stderr:
        parsed_errors = _parse_stderr(stderr)
        errors.extend(parsed_errors)

    if not has_transcript and not has_subtitle:
        if exit_code == 0:
            result_exit_code = ExitCode.PARTIAL_SUCCESS
            warnings.append("No transcript or subtitle files generated")
        else:
            result_exit_code = ExitCode.FATAL_ERROR

    output = None
    if video_id:
        output = SubtitleOutput(
            video_id=video_id,
            transcript_md=transcript_files[0] if transcript_files else None,
            srt_file=srt_files[0] if srt_files else None,
            vtt_file=vtt_files[0] if vtt_files else None,
            summary_json=summary_json_files[0] if summary_json_files else None,
            summary_md=summary_md_files[0] if summary_md_files else None,
        )

    return ExecutionResult(
        exit_code=result_exit_code,
        output=output,
        errors=errors,
        warnings=warnings,
        metadata={
            "output_dir": str(output_dir),
        },
    )


def _extract_video_id_from_dir(output_dir: Path) -> str | None:
    for f in output_dir.iterdir():
        if f.suffix in (".srt", ".md", ".json", ".vtt"):
            name = f.stem
            if name.endswith(".transcript"):
                name = name[:-10]
            if name.endswith(".summary"):
                name = name[:-7]
            if name.endswith((".zh", ".en")):
                name = name[:-3]
            if name.startswith("BV") or name.startswith("av"):
                return name
    return None


def _parse_stderr(stderr: str) -> list[dict[str, Any]]:
    errors: list[dict[str, Any]] = []
    for line in stderr.splitlines():
        line = line.strip()
        if not line:
            continue
        if "error" in line.lower() or "failed" in line.lower():
            errors.append(
                {
                    "type": "error",
                    "message": line,
                }
            )
        elif "warning" in line.lower():
            errors.append(
                {
                    "type": "warning",
                    "message": line,
                }
            )
    return errors


CONTRACT_VERSION = "1.0.0"
REQUIRED_OUTPUTS = ["*.transcript.md"]
OPTIONAL_OUTPUTS = ["*.srt", "*.vtt", "*.summary.json", "*.summary.md"]

from __future__ import annotations

import re

from ..segment import Segment


_TIME_RE = re.compile(
    r"(?P<sh>\d{2}):(?P<sm>\d{2}):(?P<ss>\d{2}),(?P<sms>\d{3})\s*-->\s*"
    r"(?P<eh>\d{2}):(?P<em>\d{2}):(?P<es>\d{2}),(?P<ems>\d{3})"
)


def _to_ms(h: str, m: str, s: str, ms: str) -> int:
    return (int(h) * 3600 + int(m) * 60 + int(s)) * 1000 + int(ms)


def srt_to_segments(srt_text: str) -> list[Segment]:
    blocks = re.split(r"\r?\n\r?\n+", srt_text.strip())
    segments: list[Segment] = []
    for block in blocks:
        lines = [ln.strip("\r") for ln in block.splitlines() if ln.strip("\r").strip()]
        if len(lines) < 2:
            continue

        # Optional numeric index line.
        time_line = lines[1] if lines[0].isdigit() else lines[0]
        m = _TIME_RE.search(time_line)
        if not m:
            continue

        start_ms = _to_ms(m["sh"], m["sm"], m["ss"], m["sms"])
        end_ms = _to_ms(m["eh"], m["em"], m["es"], m["ems"])
        text_lines = lines[2:] if lines[0].isdigit() else lines[1:]
        text = " ".join(" ".join(text_lines).replace("\n", " ").split())
        segments.append(Segment(start_ms=start_ms, end_ms=end_ms, text=text))

    return segments

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path

from .bbdown_client import BBDownClient
from .url_parser import VideoRef, parse_bilibili_ref


@dataclass(frozen=True, slots=True)
class VideoMetadata:
    video_id: str
    title: str | None
    has_subtitle: bool
    has_ai_subtitle: bool
    subtitle_files: list[Path]


def detect_subtitles(
    url_or_id: str,
    output_dir: str | Path,
) -> tuple[VideoRef, VideoMetadata]:
    ref = parse_bilibili_ref(url_or_id)
    url = ref.canonical_url or ref.input_value
    output_dir = Path(output_dir)

    client = BBDownClient()
    info = client.get_video_info(url, output_dir)

    meta = VideoMetadata(
        video_id=info.video_id or ref.video_id or "unknown",
        title=info.title,
        has_subtitle=info.subtitle_info.has_subtitle,
        has_ai_subtitle=info.subtitle_info.has_ai_subtitle,
        subtitle_files=info.subtitle_files,
    )
    return ref, meta

"""
Error taxonomy with severity levels and remediation hints.

Level 1: FATAL - Cannot proceed, requires user action
Level 2: RECOVERABLE - Can continue with degraded functionality
Level 3: WARNING - Non-critical, proceed with caution
"""

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum
from typing import Literal


class ErrorLevel(Enum):
    FATAL = "fatal"
    RECOVERABLE = "recoverable"
    WARNING = "warning"


@dataclass(frozen=True, slots=True)
class Remediation:
    hint: str
    command: str | None = None
    doc_url: str | None = None


@dataclass
class SkillError(Exception):
    code: str
    level: ErrorLevel
    message: str
    remediation: Remediation | None = None

    def __str__(self) -> str:
        parts = [f"[{self.code}] {self.message}"]
        if self.remediation:
            parts.append(f"  Hint: {self.remediation.hint}")
            if self.remediation.command:
                parts.append(f"  Run: {self.remediation.command}")
            if self.remediation.doc_url:
                parts.append(f"  See: {self.remediation.doc_url}")
        return "\n".join(parts)

    def to_json(self) -> dict:
        return {
            "code": self.code,
            "level": self.level.value,
            "message": self.message,
            "remediation": {
                "hint": self.remediation.hint,
                "command": self.remediation.command,
                "doc_url": self.remediation.doc_url,
            }
            if self.remediation
            else None,
        }


class BBDownNotFoundError(SkillError):
    def __init__(self) -> None:
        super().__init__(
            code="E001",
            level=ErrorLevel.FATAL,
            message="BBDown not found in PATH",
            remediation=Remediation(
                hint="Install BBDown from GitHub releases",
                command="./install.sh",
                doc_url="https://github.com/nilaoda/BBDown/releases",
            ),
        )


class BBDownAuthError(SkillError):
    def __init__(self, details: str = "") -> None:
        super().__init__(
            code="E002",
            level=ErrorLevel.FATAL,
            message=f"BBDown authentication required{': ' + details if details else ''}",
            remediation=Remediation(
                hint="Login to Bilibili via BBDown",
                command="BBDown login",
            ),
        )


class BBDownDownloadError(SkillError):
    def __init__(self, url: str, reason: str = "") -> None:
        super().__init__(
            code="E003",
            level=ErrorLevel.RECOVERABLE,
            message=f"Failed to download: {url}{': ' + reason if reason else ''}",
            remediation=Remediation(
                hint="Check URL validity or network connection",
            ),
        )


class NoSubtitleError(SkillError):
    def __init__(self, video_id: str) -> None:
        super().__init__(
            code="E004",
            level=ErrorLevel.RECOVERABLE,
            message=f"Video {video_id} has no subtitles",
            remediation=Remediation(
                hint="ASR transcription will be attempted if DASHSCOPE_API_KEY is set",
            ),
        )


class ASRConfigError(SkillError):
    def __init__(self) -> None:
        super().__init__(
            code="E005",
            level=ErrorLevel.FATAL,
            message="DASHSCOPE_API_KEY not configured",
            remediation=Remediation(
                hint="Set DASHSCOPE_API_KEY for ASR transcription",
                command='export DASHSCOPE_API_KEY="your-key"',
            ),
        )


class AnthropicConfigError(SkillError):
    def __init__(self, feature: str = "proofreading") -> None:
        super().__init__(
            code="E006",
            level=ErrorLevel.RECOVERABLE,
            message=f"ANTHROPIC_API_KEY not configured, {feature} skipped",
            remediation=Remediation(
                hint="Set ANTHROPIC_API_KEY or use --skip-proofread --skip-summary",
                command='export ANTHROPIC_API_KEY="your-key"',
            ),
        )


class FFmpegNotFoundError(SkillError):
    def __init__(self) -> None:
        super().__init__(
            code="E007",
            level=ErrorLevel.FATAL,
            message="ffmpeg not found",
            remediation=Remediation(
                hint="ffmpeg is required for audio conversion",
                command="pixi install",
            ),
        )


class InvalidURLError(SkillError):
    def __init__(self, url: str) -> None:
        super().__init__(
            code="E008",
            level=ErrorLevel.FATAL,
            message=f"Invalid Bilibili URL or BV ID: {url}",
            remediation=Remediation(
                hint="Provide a valid URL (e.g., https://www.bilibili.com/video/BVxxx) or BV ID",
            ),
        )


class OutputWriteError(SkillError):
    def __init__(self, path: str, reason: str = "") -> None:
        super().__init__(
            code="E009",
            level=ErrorLevel.FATAL,
            message=f"Cannot write to {path}{': ' + reason if reason else ''}",
            remediation=Remediation(
                hint="Check directory permissions or use -o to specify a different output directory",
            ),
        )


class VideoNotFoundError(SkillError):
    def __init__(self, video_id: str) -> None:
        super().__init__(
            code="E010",
            level=ErrorLevel.FATAL,
            message=f"Video not found or unavailable: {video_id}",
            remediation=Remediation(
                hint="The video may be deleted, private, or region-restricted",
            ),
        )


class RateLimitError(SkillError):
    def __init__(self, retry_after: int = 60) -> None:
        super().__init__(
            code="E011",
            level=ErrorLevel.RECOVERABLE,
            message=f"Rate limited, retry after {retry_after}s",
            remediation=Remediation(
                hint="Wait and retry, or reduce request frequency",
            ),
        )


class SubtitleContentError(SkillError):
    def __init__(self, reason: str = "empty segments") -> None:
        super().__init__(
            code="E012",
            level=ErrorLevel.RECOVERABLE,
            message=f"Subtitle content issue: {reason}",
            remediation=Remediation(
                hint="Retry download or try a different subtitle language",
            ),
        )


def exit_code_for_error(error: SkillError) -> int:
    return {
        ErrorLevel.FATAL: 1,
        ErrorLevel.RECOVERABLE: 2,
        ErrorLevel.WARNING: 0,
    }[error.level]