vink 0.1.0__py3-none-any.whl

vink/__init__.py

@@ -0,0 +1,10 @@
+"""vink — turn YouTube transcripts into clean, timestamped Markdown and detailed notes."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("vink")
+except PackageNotFoundError:  # pragma: no cover - only when running from an uninstalled tree
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

vink/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Adapters: concrete implementations of ports.
+
+All I/O and third-party SDK usage lives here. Each adapter translates between
+an external system and the domain, and converts library exceptions into
+:mod:`vink.domain.errors`. Only :mod:`vink.bootstrap` should import adapters.
+"""

vink/adapters/cache/__init__.py

@@ -0,0 +1,6 @@
+"""Cache adapters: a filesystem key-value store and a caching transcript source."""
+
+from vink.adapters.cache.caching_source import CachingTranscriptSource
+from vink.adapters.cache.filesystem import FileCache
+
+__all__ = ["CachingTranscriptSource", "FileCache"]

vink/adapters/cache/caching_source.py

@@ -0,0 +1,74 @@
+"""A transcript source decorator that caches results in any :class:`~vink.ports.Cache`."""
+
+import logging
+
+from vink.adapters.cache import serialization
+from vink.domain.errors import VinkError
+from vink.domain.models import RawTranscript, TrackInfo, TrackSelection
+from vink.domain.video_ref import VideoRef
+from vink.ports.cache import Cache
+from vink.ports.transcript_source import TranscriptSource
+
+logger = logging.getLogger(__name__)
+
+
+class CachingTranscriptSource:
+    """Wraps a :class:`~vink.ports.TranscriptSource` and caches its results.
+
+    Services stay unaware of caching: they receive this object as their
+    transcript source. Corrupt entries are treated as misses and overwritten.
+
+    Args:
+        inner: The source to delegate to on a cache miss.
+        cache: Where to store serialized results.
+    """
+
+    def __init__(self, inner: TranscriptSource, cache: Cache) -> None:
+        self._inner = inner
+        self._cache = cache
+
+    def list_tracks(self, video: VideoRef) -> list[TrackInfo]:
+        """Return tracks from the cache, or fetch and cache them."""
+        key = f"v{serialization.SCHEMA_VERSION}:tracks:{video.video_id}"
+        cached = self._cache.get(key)
+        if cached is not None:
+            try:
+                return serialization.load_tracks(cached)
+            except ValueError as exc:
+                logger.warning("Discarding corrupt cache entry %s: %s", key, exc)
+
+        tracks = self._inner.list_tracks(video)
+        self._cache.set(key, serialization.dump_tracks(tracks))
+        return tracks
+
+    def fetch(self, video: VideoRef, selection: TrackSelection) -> RawTranscript:
+        """Return the transcript from the cache, or fetch and cache it."""
+        key = _transcript_key(video, selection)
+        cached = self._cache.get(key)
+        if cached is not None:
+            try:
+                transcript = serialization.load_transcript(cached)
+            except (ValueError, VinkError) as exc:
+                logger.warning("Discarding corrupt cache entry %s: %s", key, exc)
+            else:
+                logger.debug("Cache hit for %s", key)
+                return transcript
+
+        transcript = self._inner.fetch(video, selection)
+        self._cache.set(key, serialization.dump_transcript(transcript))
+        return transcript
+
+
+def _transcript_key(video: VideoRef, selection: TrackSelection) -> str:
+    """Build a cache key that uniquely identifies one fetched transcript."""
+    track = selection.track
+    return ":".join(
+        [
+            f"v{serialization.SCHEMA_VERSION}",
+            "transcript",
+            video.video_id,
+            track.language_code,
+            track.kind.value,
+            selection.translate_to or "-",
+        ]
+    )

vink/adapters/cache/filesystem.py

@@ -0,0 +1,50 @@
+"""A :class:`~vink.ports.Cache` that stores entries as files in a directory."""
+
+import hashlib
+import logging
+import os
+import tempfile
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class FileCache:
+    """Stores each entry as a UTF-8 file named after the SHA-256 of its key.
+
+    Failures are logged and treated as cache misses, never raised: the cache
+    is an optimization and must not break the main workflow.
+
+    Args:
+        directory: Directory to store entries in. Created on first write.
+    """
+
+    def __init__(self, directory: Path) -> None:
+        self._directory = directory
+
+    def get(self, key: str) -> str | None:
+        """Return the cached value for ``key``, or ``None`` on a miss or read error."""
+        path = self._path_for(key)
+        try:
+            return path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return None
+        except OSError as exc:
+            logger.warning("Ignoring unreadable cache entry %s: %s", path, exc)
+            return None
+
+    def set(self, key: str, value: str) -> None:
+        """Store ``value`` under ``key`` atomically; log and continue on failure."""
+        path = self._path_for(key)
+        try:
+            self._directory.mkdir(parents=True, exist_ok=True)
+            fd, temp_name = tempfile.mkstemp(dir=self._directory, suffix=".tmp")
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                handle.write(value)
+            Path(temp_name).replace(path)
+        except OSError as exc:
+            logger.warning("Could not write cache entry %s: %s", path, exc)
+
+    def _path_for(self, key: str) -> Path:
+        digest = hashlib.sha256(key.encode("utf-8")).hexdigest()
+        return self._directory / f"{digest}.json"

vink/adapters/cache/serialization.py

@@ -0,0 +1,95 @@
+"""JSON (de)serialization of domain models for caching.
+
+The format is versioned through :data:`SCHEMA_VERSION`, which is part of every
+cache key. Bump it whenever the shape below changes; old entries then simply
+stop matching and are refetched.
+"""
+
+import json
+from collections.abc import Sequence
+from typing import Any, Final
+
+from vink.domain.models import RawTranscript, Segment, TrackInfo, TrackKind
+from vink.domain.video_ref import VideoRef
+
+SCHEMA_VERSION: Final = 1
+
+
+def dump_tracks(tracks: Sequence[TrackInfo]) -> str:
+    """Serialize a list of tracks to JSON."""
+    return json.dumps(
+        [
+            {
+                "language_code": track.language_code,
+                "language_name": track.language_name,
+                "is_generated": track.is_generated,
+                "translation_codes": sorted(track.translation_codes),
+            }
+            for track in tracks
+        ],
+        ensure_ascii=False,
+    )
+
+
+def load_tracks(data: str) -> list[TrackInfo]:
+    """Deserialize tracks produced by :func:`dump_tracks`.
+
+    Raises:
+        ValueError: If ``data`` is not valid serialized tracks.
+    """
+    try:
+        return [
+            TrackInfo(
+                language_code=str(item["language_code"]),
+                language_name=str(item["language_name"]),
+                is_generated=bool(item["is_generated"]),
+                translation_codes=frozenset(str(c) for c in item["translation_codes"]),
+            )
+            for item in _load_json(data, list)
+        ]
+    except (KeyError, TypeError) as exc:
+        raise ValueError(f"Malformed cached tracks: {exc}") from exc
+
+
+def dump_transcript(transcript: RawTranscript) -> str:
+    """Serialize a raw transcript to JSON."""
+    return json.dumps(
+        {
+            "video_id": transcript.video.video_id,
+            "language_code": transcript.language_code,
+            "language_name": transcript.language_name,
+            "kind": transcript.kind.value,
+            "segments": [[s.start, s.duration, s.text] for s in transcript.segments],
+        },
+        ensure_ascii=False,
+    )
+
+
+def load_transcript(data: str) -> RawTranscript:
+    """Deserialize a transcript produced by :func:`dump_transcript`.
+
+    Raises:
+        ValueError: If ``data`` is not a valid serialized transcript.
+    """
+    try:
+        payload = _load_json(data, dict)
+        return RawTranscript(
+            video=VideoRef(str(payload["video_id"])),
+            language_code=str(payload["language_code"]),
+            language_name=str(payload["language_name"]),
+            kind=TrackKind(payload["kind"]),
+            segments=tuple(
+                Segment(start=float(start), duration=float(duration), text=str(text))
+                for start, duration, text in payload["segments"]
+            ),
+        )
+    except (KeyError, TypeError) as exc:
+        raise ValueError(f"Malformed cached transcript: {exc}") from exc
+
+
+def _load_json(data: str, expected: type) -> Any:
+    """Parse JSON and check the top-level type."""
+    value = json.loads(data)
+    if not isinstance(value, expected):
+        raise ValueError(f"Expected JSON {expected.__name__}, got {type(value).__name__}")
+    return value

vink/adapters/render/__init__.py

@@ -0,0 +1,5 @@
+"""Renderer adapters. Markdown today; PDF, HTML and DOCX can be added alongside."""
+
+from vink.adapters.render.markdown import MarkdownRenderer
+
+__all__ = ["MarkdownRenderer"]

vink/adapters/render/markdown.py

@@ -0,0 +1,111 @@
+"""Markdown rendering of transcripts.
+
+Output starts with YAML front matter so the files drop straight into
+Markdown-based notes apps such as Obsidian, followed by a readable header and
+one paragraph per block, each prefixed with a clickable timestamp.
+"""
+
+import json
+import re
+from typing import Final
+
+from vink.domain.models import Chunk, Paragraph, TrackKind, Transcript
+from vink.processing.timecode import format_timecode
+
+_MARKDOWN_SPECIAL: Final = re.compile(r"([\\`*_\[\]<>])")
+"""Characters that change meaning inline. Lines never start with user text, so
+block-level markers such as ``#`` or ``-`` need no escaping."""
+
+_KIND_LABELS: Final = {
+    TrackKind.MANUAL: "creator captions",
+    TrackKind.GENERATED: "auto-generated captions",
+    TrackKind.TRANSLATED: "machine-translated captions",
+}
+
+
+class MarkdownRenderer:
+    """:class:`~vink.ports.Renderer` producing CommonMark with YAML front matter."""
+
+    @property
+    def format_name(self) -> str:
+        """Identifier used to select this renderer."""
+        return "markdown"
+
+    @property
+    def file_extension(self) -> str:
+        """File extension for Markdown output."""
+        return "md"
+
+    def render_transcript(self, transcript: Transcript) -> str:
+        """Render the complete transcript with front matter and a header."""
+        sections = [
+            _front_matter(transcript),
+            f"# {_escape(transcript.metadata.title)}",
+            _summary_line(transcript),
+            "## Transcript",
+            *(_paragraph(transcript, p) for p in transcript.paragraphs),
+        ]
+        return "\n\n".join(sections) + "\n"
+
+    def render_chunk(self, transcript: Transcript, chunk: Chunk) -> str:
+        """Render one chunk with a heading that states its position and time range."""
+        heading = (
+            f"## Part {chunk.index} of {chunk.total} "
+            f"({format_timecode(chunk.start)}\u2013{format_timecode(chunk.end)})"  # en dash
+        )
+        sections = [
+            f"# {_escape(transcript.metadata.title)}",
+            heading,
+            *(_paragraph(transcript, p) for p in chunk.paragraphs),
+        ]
+        return "\n\n".join(sections) + "\n"
+
+
+def _front_matter(transcript: Transcript) -> str:
+    """Build YAML front matter. Strings are JSON-encoded, which is valid YAML."""
+    fields: dict[str, str | None] = {
+        "title": transcript.metadata.title,
+        "channel": transcript.metadata.channel,
+        "url": transcript.video.url,
+        "video_id": transcript.video.video_id,
+        "language": transcript.language_code,
+        "captions": transcript.kind.value,
+        "duration": format_timecode(transcript.duration),
+    }
+    lines = [
+        f"{key}: {json.dumps(value, ensure_ascii=False)}"
+        for key, value in fields.items()
+        if value is not None
+    ]
+    return "---\n" + "\n".join(lines) + "\n---"
+
+
+def _summary_line(transcript: Transcript) -> str:
+    """Build the one-line header under the title."""
+    metadata = transcript.metadata
+    parts: list[str] = []
+    if metadata.channel:
+        channel = _escape(metadata.channel)
+        parts.append(
+            f"**Channel:** [{channel}]({metadata.channel_url})"
+            if metadata.channel_url
+            else f"**Channel:** {channel}"
+        )
+    parts.append(f"**Duration:** {format_timecode(transcript.duration)}")
+    parts.append(
+        f"**Language:** {_escape(transcript.language_name)} ({_KIND_LABELS[transcript.kind]})"
+    )
+    parts.append(f"**Source:** <{transcript.video.url}>")
+    return " · ".join(parts)
+
+
+def _paragraph(transcript: Transcript, paragraph: Paragraph) -> str:
+    """Render one paragraph with a bold, clickable timestamp."""
+    stamp = format_timecode(paragraph.start)
+    link = transcript.video.url_at(paragraph.start)
+    return f"**[{stamp}]({link})** {_escape(paragraph.text)}"
+
+
+def _escape(text: str) -> str:
+    """Backslash-escape characters that would otherwise be read as Markdown syntax."""
+    return _MARKDOWN_SPECIAL.sub(r"\\\1", text)

vink/adapters/sinks/__init__.py

@@ -0,0 +1,5 @@
+"""Sink adapters. Local folder today; Notion, Obsidian and others can be added alongside."""
+
+from vink.adapters.sinks.local import LocalDirectorySink
+
+__all__ = ["LocalDirectorySink"]

vink/adapters/sinks/local.py

@@ -0,0 +1,51 @@
+"""A :class:`~vink.ports.Sink` that writes files into a local directory."""
+
+import logging
+import os
+import tempfile
+from pathlib import Path
+
+from vink.domain.errors import SinkError
+
+logger = logging.getLogger(__name__)
+
+
+class LocalDirectorySink:
+    """Writes each output as a UTF-8 file inside one directory.
+
+    Names must be plain file names: anything containing a path separator or
+    referring to a parent directory is rejected, so output can never escape
+    the configured directory. Existing files with the same name are replaced.
+
+    Args:
+        directory: Destination directory. Created on first write.
+    """
+
+    def __init__(self, directory: Path) -> None:
+        self._directory = directory
+
+    def write(self, name: str, content: str) -> str:
+        """Write ``content`` to ``<directory>/<name>`` atomically.
+
+        Returns:
+            The absolute path of the written file.
+
+        Raises:
+            SinkError: If ``name`` is not a plain file name or the write fails.
+        """
+        if not name or Path(name).name != name or name in {".", ".."}:
+            raise SinkError(f"Refusing to write to unsafe file name {name!r}.")
+
+        target = self._directory / name
+        try:
+            self._directory.mkdir(parents=True, exist_ok=True)
+            fd, temp_name = tempfile.mkstemp(dir=self._directory, suffix=".tmp")
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                handle.write(content)
+            Path(temp_name).replace(target)
+        except OSError as exc:
+            raise SinkError(f"Could not write {target}: {exc}") from exc
+
+        location = str(target.resolve())
+        logger.info("Wrote %s", location)
+        return location

vink/adapters/youtube/__init__.py

@@ -0,0 +1,6 @@
+"""YouTube adapters: caption tracks via ``youtube-transcript-api``, metadata via oEmbed."""
+
+from vink.adapters.youtube.oembed import OEmbedMetadataSource
+from vink.adapters.youtube.transcript_source import YouTubeTranscriptSource
+
+__all__ = ["OEmbedMetadataSource", "YouTubeTranscriptSource"]

vink/adapters/youtube/oembed.py

@@ -0,0 +1,63 @@
+"""Video metadata from YouTube's public oEmbed endpoint.
+
+oEmbed returns the title and channel without an API key and is far lighter
+than downloading the watch page. It does not provide duration or chapters;
+those will come from a richer adapter (e.g. ``yt-dlp``) when needed.
+"""
+
+import logging
+from typing import Final
+
+import httpx
+
+from vink.domain.errors import MetadataFetchError
+from vink.domain.models import VideoMetadata
+from vink.domain.video_ref import VideoRef
+
+logger = logging.getLogger(__name__)
+
+OEMBED_URL: Final = "https://www.youtube.com/oembed"
+
+
+class OEmbedMetadataSource:
+    """:class:`~vink.ports.MetadataSource` backed by YouTube oEmbed.
+
+    Args:
+        client: HTTP client to use. The caller owns it and must close it.
+            It should be configured with timeouts and a ``User-Agent``.
+    """
+
+    def __init__(self, client: httpx.Client) -> None:
+        self._client = client
+
+    def get_metadata(self, video: VideoRef) -> VideoMetadata:
+        """Return the title and channel of ``video``.
+
+        Raises:
+            MetadataFetchError: If the request fails or the response is malformed.
+        """
+        try:
+            response = self._client.get(OEMBED_URL, params={"url": video.url, "format": "json"})
+            response.raise_for_status()
+            payload = response.json()
+        except httpx.HTTPStatusError as exc:
+            raise MetadataFetchError(
+                f"Metadata lookup for {video.video_id} failed with HTTP {exc.response.status_code}."
+            ) from exc
+        except (httpx.HTTPError, ValueError) as exc:
+            raise MetadataFetchError(f"Metadata lookup for {video.video_id} failed: {exc}") from exc
+
+        title = payload.get("title") if isinstance(payload, dict) else None
+        if not isinstance(title, str) or not title:
+            raise MetadataFetchError(f"Metadata for {video.video_id} has no title.")
+
+        return VideoMetadata(
+            title=title,
+            channel=_optional_str(payload.get("author_name")),
+            channel_url=_optional_str(payload.get("author_url")),
+        )
+
+
+def _optional_str(value: object) -> str | None:
+    """Return ``value`` if it is a non-empty string, else ``None``."""
+    return value if isinstance(value, str) and value else None

vink/adapters/youtube/transcript_source.py

@@ -0,0 +1,126 @@
+"""Caption tracks from YouTube via the open-source ``youtube-transcript-api`` library.
+
+The library reads the same internal endpoints YouTube's own player uses, so no
+API key is required. See ``docs/adr/0002-transcripts-without-data-api.md``.
+"""
+
+import logging
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from youtube_transcript_api import (
+    AgeRestricted,
+    CouldNotRetrieveTranscript,
+    InvalidVideoId,
+    IpBlocked,
+    NoTranscriptFound,
+    NotTranslatable,
+    RequestBlocked,
+    TranscriptsDisabled,
+    TranslationLanguageNotAvailable,
+    VideoUnavailable,
+    VideoUnplayable,
+    YouTubeTranscriptApi,
+)
+from youtube_transcript_api import Transcript as LibraryTranscript
+
+from vink.domain.errors import (
+    LanguageUnavailableError,
+    TranscriptFetchError,
+    TranscriptsDisabledError,
+    VideoUnavailableError,
+)
+from vink.domain.models import RawTranscript, Segment, TrackInfo, TrackSelection
+from vink.domain.video_ref import VideoRef
+
+logger = logging.getLogger(__name__)
+
+
+class YouTubeTranscriptSource:
+    """:class:`~vink.ports.TranscriptSource` backed by ``youtube-transcript-api``.
+
+    Args:
+        api: Library client to use. Inject a configured instance to set a proxy
+            or a custom HTTP session; defaults to a plain client.
+    """
+
+    def __init__(self, api: YouTubeTranscriptApi | None = None) -> None:
+        self._api = api or YouTubeTranscriptApi()
+
+    def list_tracks(self, video: VideoRef) -> list[TrackInfo]:
+        """Return every caption track available for ``video``."""
+        with _translate_errors(video.video_id):
+            transcript_list = self._api.list(video.video_id)
+            tracks = [_to_track_info(item) for item in transcript_list]
+        logger.debug("Found %d caption tracks for %s", len(tracks), video.video_id)
+        return tracks
+
+    def fetch(self, video: VideoRef, selection: TrackSelection) -> RawTranscript:
+        """Fetch the transcript described by ``selection``."""
+        track = selection.track
+        with _translate_errors(video.video_id, requested=selection.language_code):
+            transcript_list = self._api.list(video.video_id)
+            if track.is_generated:
+                source = transcript_list.find_generated_transcript([track.language_code])
+            else:
+                source = transcript_list.find_manually_created_transcript([track.language_code])
+            if selection.translate_to:
+                source = source.translate(selection.translate_to)
+            fetched = source.fetch()
+
+        segments = tuple(
+            Segment(start=snippet.start, duration=snippet.duration, text=snippet.text)
+            for snippet in fetched.snippets
+        )
+        logger.info(
+            "Fetched %d segments (%s, %s) for %s",
+            len(segments),
+            selection.language_code,
+            selection.kind,
+            video.video_id,
+        )
+        return RawTranscript(
+            video=video,
+            language_code=selection.language_code,
+            language_name=source.language,
+            kind=selection.kind,
+            segments=segments,
+        )
+
+
+def _to_track_info(item: LibraryTranscript) -> TrackInfo:
+    """Convert a library transcript descriptor into a domain :class:`TrackInfo`."""
+    return TrackInfo(
+        language_code=item.language_code,
+        language_name=item.language,
+        is_generated=item.is_generated,
+        translation_codes=frozenset(lang.language_code for lang in item.translation_languages),
+    )
+
+
+@contextmanager
+def _translate_errors(video_id: str, requested: str | None = None) -> Iterator[None]:
+    """Convert ``youtube-transcript-api`` and network exceptions into domain errors."""
+    try:
+        yield
+    except TranscriptsDisabled as exc:
+        raise TranscriptsDisabledError(video_id) from exc
+    except (VideoUnavailable, InvalidVideoId) as exc:
+        raise VideoUnavailableError(video_id, "the video does not exist or was removed") from exc
+    except AgeRestricted as exc:
+        raise VideoUnavailableError(video_id, "the video is age-restricted") from exc
+    except VideoUnplayable as exc:
+        raise VideoUnavailableError(video_id, "the video is not playable") from exc
+    except (NoTranscriptFound, NotTranslatable, TranslationLanguageNotAvailable) as exc:
+        raise LanguageUnavailableError(
+            video_id, requested=[requested] if requested else [], available=[]
+        ) from exc
+    except (RequestBlocked, IpBlocked) as exc:
+        raise TranscriptFetchError(
+            "YouTube is blocking requests from this network (common on cloud servers). "
+            "Run vink from a home or office connection, or configure a proxy."
+        ) from exc
+    except CouldNotRetrieveTranscript as exc:
+        raise TranscriptFetchError(f"Could not retrieve transcript for {video_id}.") from exc
+    except OSError as exc:  # requests.RequestException derives from OSError
+        raise TranscriptFetchError(f"Network error while contacting YouTube: {exc}") from exc