clipscribe 0.1.0__tar.gz

clipscribe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omar Taoufik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clipscribe-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: clipscribe
+Version: 0.1.0
+Summary: Extract transcripts from YouTube, TikTok, and Instagram URLs.
+Author-email: Omar Taoufik <omartaoufik26@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/darkknight127/clipscribe
+Project-URL: Repository, https://github.com/darkknight127/clipscribe
+Project-URL: Issues, https://github.com/darkknight127/clipscribe/issues
+Keywords: transcript,youtube,tiktok,instagram,whisper,captions
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: youtube
+Requires-Dist: youtube-transcript-api>=1.1.0; extra == "youtube"
+Provides-Extra: tiktok
+Requires-Dist: yt-dlp>=2024.8.6; extra == "tiktok"
+Requires-Dist: faster-whisper>=1.0.0; extra == "tiktok"
+Requires-Dist: imageio-ffmpeg>=0.5.0; extra == "tiktok"
+Provides-Extra: instagram
+Requires-Dist: yt-dlp>=2024.8.6; extra == "instagram"
+Requires-Dist: faster-whisper>=1.0.0; extra == "instagram"
+Requires-Dist: imageio-ffmpeg>=0.5.0; extra == "instagram"
+Provides-Extra: all
+Requires-Dist: youtube-transcript-api>=1.1.0; extra == "all"
+Requires-Dist: yt-dlp>=2024.8.6; extra == "all"
+Requires-Dist: faster-whisper>=1.0.0; extra == "all"
+Requires-Dist: imageio-ffmpeg>=0.5.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# clipscribe
+
+Extract transcripts from YouTube, TikTok, and Instagram URLs.
+
+YouTube uses `youtube-transcript-api`. TikTok and Instagram use yt-dlp + faster-whisper.
+
+This is a **0.1.0** library. Site extractors break when platforms change pages. Keep `yt-dlp` updated if you use TikTok or Instagram.
+
+Source: [github.com/darkknight127/clipscribe](https://github.com/darkknight127/clipscribe)
+
+## Install
+
+Pick the platforms you need, or install all of them:
+
+```bash
+pip install "clipscribe[youtube]"
+pip install "clipscribe[tiktok]"
+pip install "clipscribe[instagram]"
+pip install "clipscribe[youtube,tiktok]"
+pip install "clipscribe[all]"
+```
+
+TikTok and Instagram download Whisper models on first use. ffmpeg comes from `imageio-ffmpeg`; no system install is required.
+
+From this repo:
+
+```bash
+pip install -e ".[all,dev]"
+```
+
+If TikTok/Instagram downloads start failing, upgrade the extractor stack:
+
+```bash
+pip install -U yt-dlp imageio-ffmpeg
+```
+
+## Usage
+
+```python
+from clipscribe import TranscriptExtractor
+
+api = TranscriptExtractor()
+result = api.extract("https://www.youtube.com/watch?v=VIDEO_ID")
+
+print(result.full_text)
+print(result.to_dict())
+```
+
+Batch (failed URLs are skipped and logged):
+
+```python
+results = api.extract_many([url1, url2, url3])
+```
+
+Save files under `output/` relative to the current working directory (`json` by default). Choose from `json`, `txt`, `srt`:
+
+```python
+result = api.extract(url, save=True)
+
+api = TranscriptExtractor(allowed_outputs=["json", "srt"])
+result = api.extract(url, save=True)
+
+result = api.extract(url, save=True, allowed_outputs=["srt"])
+```
+
+Retry flaky TikTok downloads:
+
+```python
+result = api.extract(tiktok_url, max_retries=2)
+```
+
+TikTok often needs cookies when the site blocks anonymous requests:
+
+```python
+api = TranscriptExtractor(tiktok_cookies_from_browser="firefox")
+```
+
+Or a Netscape cookies file:
+
+```python
+api = TranscriptExtractor(tiktok_cookies="tiktok_cookies.txt")
+```
+
+YouTube proxy (optional):
+
+```python
+from clipscribe import GenericProxyConfig, TranscriptExtractor
+
+api = TranscriptExtractor(
+    youtube_proxy_config=GenericProxyConfig(
+        http_url="http://user:pass@host:port",
+        https_url="http://user:pass@host:port",
+    )
+)
+```
+
+Instagram needs auth. Browser cookies are the most reliable. This also requires the `instagram` extra:
+
+```python
+api = TranscriptExtractor(instagram_cookies_from_browser="firefox")
+result = api.extract("https://www.instagram.com/reel/REEL_ID/")
+```
+
+Or a Netscape cookies file:
+
+```python
+api = TranscriptExtractor(instagram_cookies="instagram_cookies.txt")
+```
+
+TikTok and Instagram videos longer than 15 minutes are rejected unless you raise or disable the cap:
+
+```python
+api = TranscriptExtractor(max_duration_s=None)
+```
+
+## Notes
+
+- First TikTok/Instagram run may download a Whisper model and ffmpeg. That needs disk and network.
+- Default Whisper model is `tiny` (speed over accuracy).
+- `YouTubeTranscriptApi` is not thread-safe. Use one `TranscriptExtractor` per thread.
+- `register()` is per instance, not global.
+- You are responsible for complying with YouTube, TikTok, and Instagram terms of use.

clipscribe-0.1.0/README.md

@@ -0,0 +1,122 @@
+# clipscribe
+
+Extract transcripts from YouTube, TikTok, and Instagram URLs.
+
+YouTube uses `youtube-transcript-api`. TikTok and Instagram use yt-dlp + faster-whisper.
+
+This is a **0.1.0** library. Site extractors break when platforms change pages. Keep `yt-dlp` updated if you use TikTok or Instagram.
+
+Source: [github.com/darkknight127/clipscribe](https://github.com/darkknight127/clipscribe)
+
+## Install
+
+Pick the platforms you need, or install all of them:
+
+```bash
+pip install "clipscribe[youtube]"
+pip install "clipscribe[tiktok]"
+pip install "clipscribe[instagram]"
+pip install "clipscribe[youtube,tiktok]"
+pip install "clipscribe[all]"
+```
+
+TikTok and Instagram download Whisper models on first use. ffmpeg comes from `imageio-ffmpeg`; no system install is required.
+
+From this repo:
+
+```bash
+pip install -e ".[all,dev]"
+```
+
+If TikTok/Instagram downloads start failing, upgrade the extractor stack:
+
+```bash
+pip install -U yt-dlp imageio-ffmpeg
+```
+
+## Usage
+
+```python
+from clipscribe import TranscriptExtractor
+
+api = TranscriptExtractor()
+result = api.extract("https://www.youtube.com/watch?v=VIDEO_ID")
+
+print(result.full_text)
+print(result.to_dict())
+```
+
+Batch (failed URLs are skipped and logged):
+
+```python
+results = api.extract_many([url1, url2, url3])
+```
+
+Save files under `output/` relative to the current working directory (`json` by default). Choose from `json`, `txt`, `srt`:
+
+```python
+result = api.extract(url, save=True)
+
+api = TranscriptExtractor(allowed_outputs=["json", "srt"])
+result = api.extract(url, save=True)
+
+result = api.extract(url, save=True, allowed_outputs=["srt"])
+```
+
+Retry flaky TikTok downloads:
+
+```python
+result = api.extract(tiktok_url, max_retries=2)
+```
+
+TikTok often needs cookies when the site blocks anonymous requests:
+
+```python
+api = TranscriptExtractor(tiktok_cookies_from_browser="firefox")
+```
+
+Or a Netscape cookies file:
+
+```python
+api = TranscriptExtractor(tiktok_cookies="tiktok_cookies.txt")
+```
+
+YouTube proxy (optional):
+
+```python
+from clipscribe import GenericProxyConfig, TranscriptExtractor
+
+api = TranscriptExtractor(
+    youtube_proxy_config=GenericProxyConfig(
+        http_url="http://user:pass@host:port",
+        https_url="http://user:pass@host:port",
+    )
+)
+```
+
+Instagram needs auth. Browser cookies are the most reliable. This also requires the `instagram` extra:
+
+```python
+api = TranscriptExtractor(instagram_cookies_from_browser="firefox")
+result = api.extract("https://www.instagram.com/reel/REEL_ID/")
+```
+
+Or a Netscape cookies file:
+
+```python
+api = TranscriptExtractor(instagram_cookies="instagram_cookies.txt")
+```
+
+TikTok and Instagram videos longer than 15 minutes are rejected unless you raise or disable the cap:
+
+```python
+api = TranscriptExtractor(max_duration_s=None)
+```
+
+## Notes
+
+- First TikTok/Instagram run may download a Whisper model and ffmpeg. That needs disk and network.
+- Default Whisper model is `tiny` (speed over accuracy).
+- `YouTubeTranscriptApi` is not thread-safe. Use one `TranscriptExtractor` per thread.
+- `register()` is per instance, not global.
+- You are responsible for complying with YouTube, TikTok, and Instagram terms of use.

clipscribe-0.1.0/clipscribe/__init__.py

@@ -0,0 +1,52 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .extractor import ExtractionResponse, TranscriptExtractor
+from .utils.extras import missing_extra
+from .utils.transcript_utils import (
+    TranscriptResult,
+    TranscriptSaver,
+    TranscriptSegment,
+    TranscriptSource,
+)
+
+try:
+    __version__ = version("clipscribe")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = [
+    "ExtractionResponse",
+    "GenericProxyConfig",
+    "InstagramTranscriptExtractor",
+    "TikTokTranscriptExtractor",
+    "TranscriptExtractor",
+    "TranscriptResult",
+    "TranscriptSaver",
+    "TranscriptSegment",
+    "TranscriptSource",
+    "YouTubeTranscriptExtractor",
+    "__version__",
+]
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))
+
+
+def __getattr__(name: str):
+    if name == "GenericProxyConfig":
+        try:
+            from youtube_transcript_api.proxies import GenericProxyConfig
+        except ImportError as exc:
+            raise missing_extra("youtube", "YouTube proxy config") from exc
+        return GenericProxyConfig
+    if name == "YouTubeTranscriptExtractor":
+        from .utils.youtube_utils import YouTubeTranscriptExtractor
+        return YouTubeTranscriptExtractor
+    if name == "TikTokTranscriptExtractor":
+        from .utils.tiktok_utils import TikTokTranscriptExtractor
+        return TikTokTranscriptExtractor
+    if name == "InstagramTranscriptExtractor":
+        from .utils.instagram_utils import InstagramTranscriptExtractor
+        return InstagramTranscriptExtractor
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

clipscribe-0.1.0/clipscribe/extractor.py

@@ -0,0 +1,295 @@
+"""Unified transcript extraction API for YouTube, TikTok, and Instagram."""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+from typing import Callable
+
+from .utils.transcript_utils import PlatformExtractor, TranscriptResult, TranscriptSaver
+
+log = logging.getLogger(__name__)
+
+_NON_RETRYABLE = (ValueError, FileNotFoundError, ImportError)
+
+
+class ExtractionResponse:
+    """
+    Wraps a TranscriptResult alongside optional save paths.
+    This is what TranscriptExtractor.extract() always returns.
+
+    Attributes:
+        result:     The raw TranscriptResult (segments, metadata, full_text).
+        saved:      Dict of format -> Path if save=True, else None.
+        url:        The original URL that was extracted.
+        platform:   Detected TranscriptSource.
+    """
+
+    def __init__(self, result: TranscriptResult, saved: dict | None = None):
+        self.result = result
+        self.saved = saved
+        self.url = result.url
+        self.platform = result.source
+
+    @property
+    def full_text(self) -> str:
+        return self.result.full_text
+
+    @property
+    def segments(self):
+        return self.result.segments
+
+    @property
+    def metadata(self):
+        return self.result.metadata
+
+    def to_dict(self) -> dict:
+        data = self.result.to_dict()
+        if self.saved:
+            data["saved_files"] = {k: str(v) for k, v in self.saved.items()}
+        return data
+
+    def __repr__(self) -> str:
+        return (
+            f"<ExtractionResponse platform={self.platform.value!r} "
+            f"segments={len(self.segments)} url={self.url!r}>"
+        )
+
+
+class TranscriptExtractor:
+    """
+    Unified transcript extraction API.
+
+    Built-in extractors and extra platforms added via ``register()`` are
+    per-instance.
+
+    Args:
+        language:        Preferred transcript language for YouTube (default: "en").
+        whisper_model:   faster-whisper model size for TikTok/Instagram (default: "tiny").
+        whisper_device:  "cpu" or "cuda" (default: "cpu").
+        whisper_compute: Quantization type for faster-whisper (default: "int8").
+        output_dir:      Directory for saved transcripts (default: "output", relative to CWD).
+        allowed_outputs: File formats to write when save=True.
+                         Choose from "json", "txt", "srt" (default: json).
+        on_error:        Optional callback(url, exc) called on per-URL failures
+                         in extract_many(). Defaults to logging the error.
+        youtube_proxy_config: Optional youtube-transcript-api ProxyConfig.
+        tiktok_cookies_from_browser: Browser name for TikTok cookies.
+        tiktok_cookies:  Netscape cookies.txt path for TikTok.
+        instagram_cookies_from_browser: Browser name for Instagram cookies.
+        instagram_cookies: Netscape cookies.txt path for Instagram.
+        max_duration_s:  Reject TikTok/Instagram videos longer than this
+                         (default: 900). Pass None for no limit.
+    """
+
+    def __init__(
+        self,
+        language: str = "en",
+        whisper_model: str = "tiny",
+        whisper_device: str = "cpu",
+        whisper_compute: str = "int8",
+        output_dir: str = "output",
+        allowed_outputs: list[str] | None = None,
+        on_error: Callable[[str, Exception], None] | None = None,
+        instagram_cookies_from_browser: str | None = None,
+        instagram_cookies: str | None = None,
+        tiktok_cookies_from_browser: str | None = None,
+        tiktok_cookies: str | None = None,
+        youtube_proxy_config=None,
+        max_duration_s: int | None = 900,
+    ):
+        self._saver = TranscriptSaver(output_dir=output_dir, allowed_outputs=allowed_outputs)
+        self._on_error = on_error or self._default_error_handler
+        self._registry: list[tuple[re.Pattern, PlatformExtractor]] = []
+        self._extra: list[tuple[re.Pattern, PlatformExtractor]] = []
+
+        self._register_defaults(
+            language=language,
+            whisper_model=whisper_model,
+            whisper_device=whisper_device,
+            whisper_compute=whisper_compute,
+            instagram_cookies_from_browser=instagram_cookies_from_browser,
+            instagram_cookies=instagram_cookies,
+            tiktok_cookies_from_browser=tiktok_cookies_from_browser,
+            tiktok_cookies=tiktok_cookies,
+            youtube_proxy_config=youtube_proxy_config,
+            max_duration_s=max_duration_s,
+        )
+
+    def extract(
+        self,
+        url: str,
+        save: bool = False,
+        max_retries: int = 0,
+        allowed_outputs: list[str] | None = None,
+    ) -> ExtractionResponse:
+        """
+        Extract transcript from a single URL.
+
+        Args:
+            url:              A YouTube, TikTok, or Instagram URL (or any registered platform).
+            save:             If True, saves files to the configured output_dir.
+            max_retries:      Extra attempts after a failed extract (default: 0).
+            allowed_outputs:  Formats for this call only. Choose from
+                              "json", "txt", "srt". Defaults to the instance list.
+
+        Returns:
+            ExtractionResponse with .full_text, .segments, .metadata, .to_dict()
+
+        Raises:
+            ValueError:   If the URL doesn't match any registered platform.
+            RuntimeError: If extraction fails.
+            ImportError:  If the matching platform extra is not installed.
+        """
+        extractor = self._resolve(url)
+        if allowed_outputs is not None and not save:
+            log.warning("allowed_outputs is ignored because save=False")
+        max_retries = max(0, max_retries)
+        result: TranscriptResult | None = None
+        for attempt in range(max_retries + 1):
+            try:
+                result = extractor.extract(url)
+                break
+            except _NON_RETRYABLE:
+                raise
+            except Exception:
+                if attempt >= max_retries:
+                    raise
+                time.sleep(min(8, 2 ** attempt))
+        if result is None:
+            raise RuntimeError(f"Extraction failed for {url}")
+        saved = (
+            self._saver.save(result, self._slug(result), allowed_outputs=allowed_outputs)
+            if save
+            else None
+        )
+        return ExtractionResponse(result=result, saved=saved)
+
+    def extract_many(
+        self,
+        urls: list[str],
+        save: bool = False,
+        max_retries: int = 0,
+        allowed_outputs: list[str] | None = None,
+    ) -> list[ExtractionResponse]:
+        """
+        Extract transcripts from multiple URLs.
+        Failures are caught, passed to on_error, and skipped — processing continues.
+        """
+        if allowed_outputs is not None and not save:
+            log.warning("allowed_outputs is ignored because save=False")
+            allowed_outputs = None
+        responses = []
+        for url in urls:
+            try:
+                responses.append(
+                    self.extract(
+                        url,
+                        save=save,
+                        max_retries=max_retries,
+                        allowed_outputs=allowed_outputs,
+                    )
+                )
+            except Exception as exc:
+                self._on_error(url, exc)
+        return responses
+
+    def supports(self, url: str) -> bool:
+        """Return True if the URL matches a registered platform."""
+        try:
+            self._resolve(url)
+            return True
+        except ValueError:
+            return False
+
+    def register(self, url_pattern: str, extractor: PlatformExtractor) -> None:
+        """
+        Register a new platform extractor on this instance.
+
+        Args:
+            url_pattern: A regex string matched against the full URL.
+            extractor:   Any object with an .extract(url) -> TranscriptResult method.
+        """
+        self._extra.append((re.compile(url_pattern, re.IGNORECASE), extractor))
+
+    def _register_defaults(
+        self,
+        language: str,
+        whisper_model: str,
+        whisper_device: str,
+        whisper_compute: str,
+        instagram_cookies_from_browser: str | None = None,
+        instagram_cookies: str | None = None,
+        tiktok_cookies_from_browser: str | None = None,
+        tiktok_cookies: str | None = None,
+        youtube_proxy_config=None,
+        max_duration_s: int | None = 900,
+    ) -> None:
+        from .utils.youtube_utils import YouTubeTranscriptExtractor
+        from .utils.tiktok_utils import TikTokTranscriptExtractor
+
+        self._registry = [
+            (
+                re.compile(r"youtube\.com|youtu\.be", re.IGNORECASE),
+                YouTubeTranscriptExtractor(
+                    language=language,
+                    proxy_config=youtube_proxy_config,
+                ),
+            ),
+            (
+                re.compile(r"tiktok\.com", re.IGNORECASE),
+                TikTokTranscriptExtractor(
+                    whisper_model=whisper_model,
+                    device=whisper_device,
+                    compute_type=whisper_compute,
+                    cookies_from_browser=tiktok_cookies_from_browser,
+                    cookies_file=tiktok_cookies,
+                    max_duration_s=max_duration_s,
+                ),
+            ),
+        ]
+
+        if instagram_cookies_from_browser or instagram_cookies:
+            from .utils.instagram_utils import InstagramTranscriptExtractor
+
+            self._registry.append((
+                re.compile(r"instagram\.com", re.IGNORECASE),
+                InstagramTranscriptExtractor(
+                    cookies_from_browser=instagram_cookies_from_browser,
+                    cookies_file=instagram_cookies,
+                    whisper_model=whisper_model,
+                    device=whisper_device,
+                    compute_type=whisper_compute,
+                    max_duration_s=max_duration_s,
+                ),
+            ))
+
+    def _resolve(self, url: str) -> PlatformExtractor:
+        for pattern, extractor in (*self._registry, *self._extra):
+            if pattern.search(url):
+                return extractor
+        if "instagram.com" in url.lower():
+            raise ValueError(
+                "Instagram URLs require authentication. "
+                "Pass instagram_cookies_from_browser or instagram_cookies."
+            )
+        raise ValueError(
+            f"No extractor registered for URL: {url}\n"
+            f"Registered platforms: {self._registered_platforms()}"
+        )
+
+    def _slug(self, result: TranscriptResult) -> str:
+        media_id = (
+            result.metadata.get("video_id")
+            or result.metadata.get("post_id")
+            or "unknown"
+        )
+        return re.sub(r'[\\/*?:"<>|]', "_", f"{result.source.value}_{media_id}").strip()
+
+    def _registered_platforms(self) -> list[str]:
+        return [pattern.pattern for pattern, _ in (*self._registry, *self._extra)]
+
+    @staticmethod
+    def _default_error_handler(url: str, exc: Exception) -> None:
+        log.error("Failed (%s): %s", url, exc)

clipscribe-0.1.0/clipscribe/utils/extras.py

@@ -0,0 +1,10 @@
+"""Install-extra hints for optional platform dependencies."""
+
+def extra_install(platform: str) -> str:
+    return f'pip install "clipscribe[{platform}]" or "clipscribe[all]"'
+
+
+def missing_extra(platform: str, what: str) -> ImportError:
+    return ImportError(
+        f"{what} requires extra dependencies. Install with: {extra_install(platform)}"
+    )