Upload 30 files

renderer/audio/mixer.py

@@ -19,20 +19,27 @@ class AudioMixer:
             "[ducked][voice]amix=inputs=2:duration=first:dropout_transition=2[aout]"
         )
 
-    def mix(self, video: Path, music: str | None, voiceover: str | None, output: Path) -> Path:
+    def mix(self, video: Path, music: str | None, voiceover: str | None, output: Path, normalize: bool = False) -> Path:
+        audio_tail = ",loudnorm=I=-16:TP=-1.5:LRA=11" if normalize else ""
         if not music and not voiceover:
             command = FFmpegCommand().add("-hide_banner").input(video).add("-c", "copy").overwrite().add(output).build()
             self.runner.run(command)
             return output
         if voiceover and music:
+            ducking_filter = self.ducking_filter()
+            if normalize:
+                ducking_filter += ";[aout]loudnorm=I=-16:TP=-1.5:LRA=11[anorm]"
+                audio_map = "[anorm]"
+            else:
+                audio_map = "[aout]"
             command = (
                 FFmpegCommand()
                 .add("-hide_banner")
                 .input(video)
                 .input(music)
                 .input(voiceover)
-                .add("-filter_complex", self.ducking_filter())
-                .add("-map", "0:v", "-map", "[aout]", "-c:v", "copy", "-c:a", "aac", "-shortest")
+                .add("-filter_complex", ducking_filter)
+                .add("-map", "0:v", "-map", audio_map, "-c:v", "copy", "-c:a", "aac", "-shortest")
                 .overwrite()
                 .add(output)
                 .build()
@@ -45,7 +52,7 @@ class AudioMixer:
                 .add("-hide_banner")
                 .input(video)
                 .input(audio)
-                .add("-filter_complex", f"[1:a]volume={volume}[aout]")
+                .add("-filter_complex", f"[1:a]volume={volume}{audio_tail}[aout]")
                 .add("-map", "0:v", "-map", "[aout]", "-c:v", "copy", "-c:a", "aac", "-shortest")
                 .overwrite()
                 .add(output)

renderer/core/config.py

@@ -15,7 +15,9 @@ class Settings:
     temp_dir: Path = Path(os.getenv("TEMP_DIR", str(DEFAULT_ROOT / "temp")))
     exports_dir: Path = Path(os.getenv("EXPORTS_DIR", str(DEFAULT_ROOT / "exports")))
     jobs_dir: Path = Path(os.getenv("JOBS_DIR", str(DEFAULT_ROOT / "jobs")))
+    storage_dir: Path = Path(os.getenv("STORAGE_DIR", str(DEFAULT_ROOT / "storage")))
     metadata_cache: Path = Path(os.getenv("METADATA_CACHE", str(DEFAULT_ROOT / "temp" / "metadata_cache.json")))
+    signing_secret: str = os.getenv("BASYX_SIGNING_SECRET", "dev-secret-change-me")
     font_path: Path = Path(os.getenv("FONT_PATH", "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf"))
     output_width: int = int(os.getenv("OUTPUT_WIDTH", "1080"))
     output_height: int = int(os.getenv("OUTPUT_HEIGHT", "1920"))
@@ -24,11 +26,23 @@ class Settings:
     download_timeout_seconds: int = int(os.getenv("DOWNLOAD_TIMEOUT_SECONDS", "60"))
     max_download_bytes: int = int(os.getenv("MAX_DOWNLOAD_BYTES", str(500 * 1024 * 1024)))
     allow_private_asset_urls: bool = os.getenv("ALLOW_PRIVATE_ASSET_URLS", "false").lower() == "true"
+    whisper_model_size: str = os.getenv("WHISPER_MODEL_SIZE", "tiny")
+    whisper_compute_type: str = os.getenv("WHISPER_COMPUTE_TYPE", "int8")
+    whisper_device: str = os.getenv("WHISPER_DEVICE", "cpu")
+    whisper_model_dir: Path = Path(os.getenv("WHISPER_MODEL_DIR", str(DEFAULT_ROOT / "models")))
     max_retries: int = int(os.getenv("MAX_RETRIES", "3"))
     max_workers: int = int(os.getenv("MAX_RENDER_WORKERS", "1"))
+    job_retention_seconds: int = int(os.getenv("JOB_RETENTION_SECONDS", str(24 * 3600)))
     crf: int = int(os.getenv("OUTPUT_CRF", "23"))
     preset: str = os.getenv("OUTPUT_PRESET", "veryfast")
 
     def ensure_dirs(self) -> None:
-        for directory in (self.temp_dir, self.exports_dir, self.jobs_dir, self.metadata_cache.parent):
+        for directory in (
+            self.temp_dir,
+            self.exports_dir,
+            self.jobs_dir,
+            self.storage_dir,
+            self.metadata_cache.parent,
+            self.whisper_model_dir,
+        ):
             directory.mkdir(parents=True, exist_ok=True)

renderer/core/models.py

@@ -4,7 +4,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Literal
 
-JobState = Literal["PENDING", "RUNNING", "FAILED", "COMPLETED"]
+JobState = Literal["PENDING", "RUNNING", "FAILED", "COMPLETED", "CANCEL_REQUESTED", "CANCELLED"]
 
 
 @dataclass
@@ -15,16 +15,32 @@ class Scene:
     caption: str = ""
     transition: str = "fade"
     background: str = "blur"
+    layout: str = "fill"
+    effect: str | None = None
 
 
 @dataclass
 class RenderRequest:
     scenes: list[Scene]
     template: str = "tiktok_classic"
+    preset: str | None = None
     output_name: str = "render.mp4"
     voiceover: str | None = None
     background_music: str | None = None
     subtitle_format: Literal["srt", "ass"] = "ass"
+    auto_subtitles: bool = False
+    subtitle_language: str | None = None
+    whisper_model_size: str | None = None
+    preview: bool = False
+    audio_normalize: bool = False
+    watermark: str | None = None
+    watermark_position: str = "bottom-right"
+    intro: str | None = None
+    outro: str | None = None
+    callback_url: str | None = None
+    export_target: str | None = None
+    priority: int = 0
+    scheduled_at: float | None = None
     normalize: bool = True
     metadata: dict[str, Any] = field(default_factory=dict)
 
@@ -71,6 +87,10 @@ class JobRecord:
     created_at: float
     updated_at: float
     output_path: str | None = None
+    download_token: str | None = None
+    callback_url: str | None = None
+    export_target: str | None = None
+    export_path: str | None = None
     failure_reason: str | None = None
     commands: list[list[str]] = field(default_factory=list)
     logs: list[str] = field(default_factory=list)

renderer/core/render_engine.py

@@ -17,6 +17,7 @@ from renderer.ffmpeg.normalize import Normalizer
 from renderer.ffmpeg.runner import FFmpegRunner
 from renderer.scenes import Timeline
 from renderer.subtitles import SubtitleGenerator
+from renderer.transcription import WhisperTranscriber
 from renderer.transitions import TransitionBuilder
 
 
@@ -31,6 +32,7 @@ class RenderEngine:
         self.assets = AssetProbe(self.settings.metadata_cache)
         self.normalizer = Normalizer(self.settings, self.runner)
         self.subtitles = SubtitleGenerator()
+        self.transcriber = WhisperTranscriber(self.settings)
         self.transitions = TransitionBuilder()
         self.audio = AudioMixer(self.runner)
         self.exports = ExportManager(self.settings.exports_dir)
@@ -47,7 +49,8 @@ class RenderEngine:
             prepared = self._prepare_scene_media(resolved, workdir)
             subtitles = self._write_subtitles(resolved, timeline, workdir)
             video = self._compose_video(prepared, resolved, subtitles, workdir)
-            mixed = self.audio.mix(video, resolved.background_music, resolved.voiceover, workdir / "mixed.mp4")
+            mixed = self.audio.mix(video, resolved.background_music, resolved.voiceover, workdir / "mixed.mp4", normalize=resolved.audio_normalize)
+            mixed = self._apply_watermark(mixed, resolved, workdir)
             output = self.exports.save(mixed, job_id, request.output_name)
             cleanup_directory(workdir, keep={mixed})
         metrics = {
@@ -90,6 +93,27 @@ class RenderEngine:
     def inspect_asset(self, path: str | Path) -> dict:
         return self.assets.probe(path).__dict__
 
+    def transcribe(
+        self,
+        audio_path: str | Path,
+        *,
+        model_size: str | None = None,
+        language: str | None = None,
+        task: str = "transcribe",
+        beam_size: int = 5,
+        vad_filter: bool = True,
+        word_timestamps: bool = True,
+    ) -> dict:
+        return self.transcriber.transcribe(
+            audio_path,
+            model_size=model_size,
+            language=language,
+            task=task,
+            beam_size=beam_size,
+            vad_filter=vad_filter,
+            word_timestamps=word_timestamps,
+        ).as_dict()
+
     def _render_resolved(self, request: RenderRequest, job_id: str, workdir: Path) -> RenderResult:
         self._commands = []
         self._logs = []
@@ -98,7 +122,8 @@ class RenderEngine:
         prepared = self._prepare_scene_media(request, workdir)
         subtitles = self._write_subtitles(request, timeline, workdir)
         video = self._compose_video(prepared, request, subtitles, workdir)
-        mixed = self.audio.mix(video, request.background_music, request.voiceover, workdir / "mixed.mp4")
+        mixed = self.audio.mix(video, request.background_music, request.voiceover, workdir / "mixed.mp4", normalize=request.audio_normalize)
+        mixed = self._apply_watermark(mixed, request, workdir)
         output = self.exports.save(mixed, job_id, request.output_name)
         metrics = {
             "render_time_seconds": round(time.time() - started, 3),
@@ -120,11 +145,24 @@ class RenderEngine:
                 self.normalizer.normalize(source, target, scene.duration)
             else:
                 shutil.copy2(source, target)
+            if request.preview:
+                preview = workdir / f"scene_{idx:03d}_preview.mp4"
+                self._scale_preview(target, preview)
+                target = preview
             prepared.append(target)
         return prepared
 
     def _write_subtitles(self, request: RenderRequest, timeline: Timeline, workdir: Path) -> Path | None:
-        events = self.subtitles.from_scenes(request.scenes, timeline.total_duration)
+        if request.auto_subtitles and request.voiceover:
+            transcript = self.transcriber.transcribe(
+                request.voiceover,
+                model_size=request.whisper_model_size,
+                language=request.subtitle_language,
+                word_timestamps=True,
+            )
+            events = transcript.subtitle_events(prefer_words=True)
+        else:
+            events = self.subtitles.from_scenes(request.scenes, timeline.total_duration)
         if not events:
             return None
         if request.subtitle_format == "srt":
@@ -163,6 +201,48 @@ class RenderEngine:
             return subtitled
         return composed
 
+    def _apply_watermark(self, video: Path, request: RenderRequest, workdir: Path) -> Path:
+        if not request.watermark:
+            return video
+        watermark = Path(request.watermark)
+        if not watermark.exists():
+            self._logs.append(f"Watermark skipped; file not found: {watermark}")
+            return video
+        output = workdir / "watermarked.mp4"
+        position = {
+            "top-left": "20:20",
+            "top-right": "W-w-20:20",
+            "bottom-left": "20:H-h-20",
+            "bottom-right": "W-w-20:H-h-20",
+            "center": "(W-w)/2:(H-h)/2",
+        }.get(request.watermark_position, "W-w-20:H-h-20")
+        command = (
+            FFmpegCommand()
+            .add("-hide_banner")
+            .input(video)
+            .input(watermark)
+            .add("-filter_complex", f"[1:v]scale=iw*0.22:-1[wm];[0:v][wm]overlay={position}")
+            .add("-c:a", "copy", "-c:v", "libx264", "-preset", self.settings.preset, "-crf", self.settings.crf)
+            .overwrite()
+            .add(output)
+            .build()
+        )
+        self._run(command)
+        return output
+
+    def _scale_preview(self, source: Path, output: Path) -> None:
+        command = (
+            FFmpegCommand()
+            .add("-hide_banner")
+            .input(source)
+            .add("-vf", "scale=540:960:force_original_aspect_ratio=decrease,pad=540:960:(ow-iw)/2:(oh-ih)/2")
+            .add("-c:v", "libx264", "-preset", "ultrafast", "-crf", "30", "-c:a", "aac")
+            .overwrite()
+            .add(output)
+            .build()
+        )
+        self._run(command)
+
     def _run(self, command: list[str]) -> None:
         result = self.runner.run(command)
         if result.stderr:

renderer/core/security.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import hmac
+import secrets
+
+
+def create_download_token(secret: str, job_id: str) -> str:
+    nonce = secrets.token_urlsafe(18)
+    signature = hmac.digest(secret.encode("utf-8"), f"{job_id}:{nonce}".encode("utf-8"), "sha256").hex()
+    return f"{nonce}.{signature}"
+
+
+def verify_download_token(secret: str, job_id: str, token: str | None) -> bool:
+    if not token or "." not in token:
+        return False
+    nonce, signature = token.split(".", 1)
+    expected = hmac.digest(secret.encode("utf-8"), f"{job_id}:{nonce}".encode("utf-8"), "sha256").hex()
+    return hmac.compare_digest(signature, expected)

renderer/jobs/manager.py

@@ -1,7 +1,12 @@
 from __future__ import annotations
 
 import concurrent.futures
+import http.client
+import json
+import shutil
 import threading
+import urllib.request
+from urllib.parse import urlparse
 from dataclasses import asdict
 from pathlib import Path
 from typing import Callable
@@ -9,6 +14,7 @@ from typing import Callable
 from renderer.core.config import Settings
 from renderer.core.models import AIReelsRequest, JobRecord, RenderRequest
 from renderer.core.render_engine import RenderEngine
+from renderer.core.security import create_download_token
 from renderer.core.utils import new_id, now, read_json, write_json
 
 
@@ -20,7 +26,11 @@ class JobManager:
         self.lock = threading.Lock()
 
     def submit_render(self, request: RenderRequest) -> str:
-        return self._submit(lambda job_id, log: RenderEngine(self.settings, log=log).render(request, job_id))
+        return self._submit(
+            lambda job_id, log: RenderEngine(self.settings, log=log).render(request, job_id),
+            callback_url=request.callback_url,
+            export_target=request.export_target,
+        )
 
     def submit_ai_reels(self, request: AIReelsRequest) -> str:
         return self._submit(lambda job_id, log: RenderEngine(self.settings, log=log).ai_reels(request, job_id))
@@ -37,9 +47,50 @@ class JobManager:
             raise KeyError(job_id)
         return JobRecord(**data)
 
-    def _submit(self, handler: Callable[[str, Callable[[str], None]], object]) -> str:
+    def cancel(self, job_id: str) -> JobRecord:
+        record = self.get(job_id)
+        if record.state == "PENDING":
+            self._update(job_id, state="CANCELLED", failure_reason="Cancelled before execution")
+        elif record.state == "RUNNING":
+            self._update(job_id, state="CANCEL_REQUESTED", failure_reason="Cancellation requested")
+        return self.get(job_id)
+
+    def cleanup(self, older_than_seconds: int | None = None) -> dict[str, int]:
+        cutoff = now() - (older_than_seconds or self.settings.job_retention_seconds)
+        removed_jobs = 0
+        removed_exports = 0
+        for path in self.settings.jobs_dir.glob("*.json"):
+            record = JobRecord(**read_json(path, {}))
+            if record.updated_at >= cutoff or record.state in {"PENDING", "RUNNING", "CANCEL_REQUESTED"}:
+                continue
+            if record.output_path:
+                output = Path(record.output_path)
+                if output.exists():
+                    output.unlink()
+                    removed_exports += 1
+            path.unlink(missing_ok=True)
+            removed_jobs += 1
+        uploads = self.settings.temp_dir / "uploads"
+        if uploads.exists():
+            shutil.rmtree(uploads, ignore_errors=True)
+        return {"removed_jobs": removed_jobs, "removed_exports": removed_exports}
+
+    def _submit(
+        self,
+        handler: Callable[[str, Callable[[str], None]], object],
+        callback_url: str | None = None,
+        export_target: str | None = None,
+    ) -> str:
         job_id = new_id()
-        record = JobRecord(job_id=job_id, state="PENDING", created_at=now(), updated_at=now())
+        record = JobRecord(
+            job_id=job_id,
+            state="PENDING",
+            created_at=now(),
+            updated_at=now(),
+            download_token=create_download_token(self.settings.signing_secret, job_id),
+            callback_url=callback_url,
+            export_target=export_target,
+        )
         self._save(record)
         self.executor.submit(self._run_with_retries, job_id, handler)
         return job_id
@@ -48,22 +99,34 @@ class JobManager:
         attempts = 0
         while attempts < self.settings.max_retries:
             attempts += 1
+            if self.get(job_id).state == "CANCELLED":
+                self._send_callback(job_id)
+                return
             self._update(job_id, state="RUNNING", metrics={"attempt": attempts})
             try:
+                if self.get(job_id).state == "CANCEL_REQUESTED":
+                    self._update(job_id, state="CANCELLED", failure_reason="Cancelled before render started")
+                    self._send_callback(job_id)
+                    return
                 result = handler(job_id, lambda message: self.append_log(job_id, message))
+                record = self.get(job_id)
+                export_path = self._export_copy(result.output_path, record.export_target, job_id)
                 self._update(
                     job_id,
                     state="COMPLETED",
                     output_path=str(result.output_path),
+                    export_path=export_path,
                     commands=result.commands,
                     logs=result.logs,
                     metrics=result.metrics | {"attempt": attempts},
                 )
+                self._send_callback(job_id)
                 return
             except Exception as exc:
                 self.append_log(job_id, f"Attempt {attempts} failed: {exc}")
                 if attempts >= self.settings.max_retries:
                     self._update(job_id, state="FAILED", failure_reason=str(exc), metrics={"attempt": attempts})
+                    self._send_callback(job_id)
 
     def append_log(self, job_id: str, message: str) -> None:
         with self.lock:
@@ -88,3 +151,65 @@ class JobManager:
 
     def _save(self, record: JobRecord) -> None:
         write_json(self._record_path(record.job_id), asdict(record))
+
+    def _export_copy(self, output_path: Path, export_target: str | None, job_id: str) -> str | None:
+        if not export_target:
+            return None
+        if export_target != "local":
+            if export_target.startswith(("http://", "https://")):
+                _put_file(export_target, output_path)
+                return export_target
+            return None
+        target_dir = self.settings.storage_dir / job_id
+        target_dir.mkdir(parents=True, exist_ok=True)
+        target = target_dir / output_path.name
+        shutil.copy2(output_path, target)
+        return str(target)
+
+    def _send_callback(self, job_id: str) -> None:
+        try:
+            record = self.get(job_id)
+        except KeyError:
+            return
+        if not record.callback_url:
+            return
+        payload = json.dumps(asdict(record), default=str).encode("utf-8")
+        request = urllib.request.Request(
+            record.callback_url,
+            data=payload,
+            headers={"Content-Type": "application/json", "User-Agent": "basyx-ffmpeg-callback/1.0"},
+            method="POST",
+        )
+        try:
+            urllib.request.urlopen(request, timeout=10).read()
+        except Exception as exc:
+            self.append_log(job_id, f"Callback delivery failed: {exc}")
+
+
+def _put_file(url: str, path: Path) -> None:
+    parsed = urlparse(url)
+    connection_cls = http.client.HTTPSConnection if parsed.scheme == "https" else http.client.HTTPConnection
+    connection = connection_cls(parsed.netloc, timeout=60)
+    target = parsed.path or "/"
+    if parsed.query:
+        target += f"?{parsed.query}"
+    headers = {
+        "Content-Type": "video/mp4",
+        "Content-Length": str(path.stat().st_size),
+        "User-Agent": "basyx-ffmpeg-export/1.0",
+    }
+    connection.putrequest("PUT", target)
+    for key, value in headers.items():
+        connection.putheader(key, value)
+    connection.endheaders()
+    with path.open("rb") as source:
+        while True:
+            chunk = source.read(1024 * 1024)
+            if not chunk:
+                break
+            connection.send(chunk)
+    response = connection.getresponse()
+    body = response.read()
+    connection.close()
+    if response.status >= 400:
+        raise RuntimeError(f"Export upload failed with HTTP {response.status}: {body[:500]!r}")

renderer/scenes/timeline.py

@@ -22,6 +22,9 @@ class Timeline:
             voiceover=payload.get("voiceover"),
             background_music=payload.get("background_music"),
             subtitle_format=payload.get("subtitle_format", "ass"),
+            auto_subtitles=payload.get("auto_subtitles", False),
+            subtitle_language=payload.get("subtitle_language"),
+            whisper_model_size=payload.get("whisper_model_size"),
             normalize=payload.get("normalize", True),
             metadata=payload.get("metadata", {}),
         )

renderer/templates/__init__.py

@@ -1,3 +1,4 @@
 from renderer.templates.caption_templates import CaptionTemplate, get_template, list_templates
+from renderer.templates.presets import apply_preset, list_presets
 
-__all__ = ["CaptionTemplate", "get_template", "list_templates"]
+__all__ = ["CaptionTemplate", "apply_preset", "get_template", "list_presets", "list_templates"]

renderer/templates/presets.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+
+PRESETS: dict[str, dict[str, Any]] = {
+    "tiktok_9_16_fast": {
+        "template": "tiktok_classic",
+        "subtitle_format": "ass",
+        "auto_subtitles": True,
+        "preview": False,
+        "normalize": True,
+    },
+    "youtube_shorts_hd": {
+        "template": "youtube_shorts",
+        "subtitle_format": "ass",
+        "auto_subtitles": True,
+        "normalize": True,
+    },
+    "podcast_square": {
+        "template": "podcast_style",
+        "subtitle_format": "ass",
+        "auto_subtitles": True,
+        "normalize": True,
+        "metadata": {"target_aspect": "1:1"},
+    },
+    "reels_with_subtitles": {
+        "template": "modern_minimal",
+        "subtitle_format": "ass",
+        "auto_subtitles": True,
+        "normalize": True,
+    },
+    "draft_preview": {
+        "template": "modern_minimal",
+        "subtitle_format": "ass",
+        "preview": True,
+        "normalize": True,
+    },
+}
+
+
+def list_presets() -> list[str]:
+    return sorted(PRESETS)
+
+
+def apply_preset(payload: dict[str, Any]) -> dict[str, Any]:
+    preset_name = payload.get("preset")
+    if not preset_name:
+        return payload
+    preset = deepcopy(PRESETS.get(preset_name, {}))
+    preset.update(payload)
+    if "metadata" in PRESETS.get(preset_name, {}) or "metadata" in payload:
+        metadata = deepcopy(PRESETS.get(preset_name, {}).get("metadata", {}))
+        metadata.update(payload.get("metadata", {}))
+        preset["metadata"] = metadata
+    return preset

renderer/transcription/__init__.py

@@ -0,0 +1,3 @@
+from renderer.transcription.whisper import TranscriptionResult, WhisperTranscriber
+
+__all__ = ["TranscriptionResult", "WhisperTranscriber"]

renderer/transcription/whisper.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from threading import Lock
+
+from renderer.core.config import Settings
+from renderer.subtitles import SubtitleEvent
+
+
+@dataclass
+class TranscriptionWord:
+    start: float
+    end: float
+    word: str
+    probability: float | None = None
+
+
+@dataclass
+class TranscriptionSegment:
+    id: int
+    start: float
+    end: float
+    text: str
+    words: list[TranscriptionWord] = field(default_factory=list)
+
+
+@dataclass
+class TranscriptionResult:
+    text: str
+    language: str | None
+    language_probability: float | None
+    duration: float | None
+    segments: list[TranscriptionSegment]
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+    def subtitle_events(self, prefer_words: bool = False) -> list[SubtitleEvent]:
+        if prefer_words:
+            words = [
+                SubtitleEvent(word.start, word.end, word.word.strip())
+                for segment in self.segments
+                for word in segment.words
+                if word.word.strip()
+            ]
+            if words:
+                return words
+        return [SubtitleEvent(segment.start, segment.end, segment.text.strip()) for segment in self.segments if segment.text.strip()]
+
+
+class WhisperTranscriber:
+    """Lazy CPU-first faster-whisper wrapper."""
+
+    _models: dict[tuple[str, str, str, str], object] = {}
+    _lock = Lock()
+
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+
+    def transcribe(
+        self,
+        audio_path: str | Path,
+        *,
+        model_size: str | None = None,
+        language: str | None = None,
+        task: str = "transcribe",
+        beam_size: int = 5,
+        vad_filter: bool = True,
+        word_timestamps: bool = True,
+    ) -> TranscriptionResult:
+        model = self._model(model_size or self.settings.whisper_model_size)
+        segments_iter, info = model.transcribe(
+            str(audio_path),
+            language=language,
+            task=task,
+            beam_size=beam_size,
+            vad_filter=vad_filter,
+            word_timestamps=word_timestamps,
+        )
+        segments: list[TranscriptionSegment] = []
+        for segment in segments_iter:
+            words = [
+                TranscriptionWord(
+                    start=float(word.start),
+                    end=float(word.end),
+                    word=word.word,
+                    probability=getattr(word, "probability", None),
+                )
+                for word in (segment.words or [])
+            ]
+            segments.append(
+                TranscriptionSegment(
+                    id=int(segment.id),
+                    start=float(segment.start),
+                    end=float(segment.end),
+                    text=segment.text.strip(),
+                    words=words,
+                )
+            )
+        return TranscriptionResult(
+            text=" ".join(segment.text for segment in segments).strip(),
+            language=getattr(info, "language", None),
+            language_probability=getattr(info, "language_probability", None),
+            duration=getattr(info, "duration", None),
+            segments=segments,
+        )
+
+    def _model(self, model_size: str):
+        key = (
+            model_size,
+            self.settings.whisper_device,
+            self.settings.whisper_compute_type,
+            str(self.settings.whisper_model_dir),
+        )
+        with self._lock:
+            if key not in self._models:
+                try:
+                    from faster_whisper import WhisperModel
+                except ImportError as exc:
+                    raise RuntimeError("faster-whisper is not installed. Install requirements.txt to enable transcription.") from exc
+                self._models[key] = WhisperModel(
+                    model_size,
+                    device=self.settings.whisper_device,
+                    compute_type=self.settings.whisper_compute_type,
+                    download_root=str(self.settings.whisper_model_dir),
+                )
+            return self._models[key]