Metadata-Version: 2.4
Name: clipscribe
Version: 0.1.1
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

[![PyPI](https://img.shields.io/pypi/v/clipscribe.svg)](https://pypi.org/project/clipscribe/)

Extract transcripts from YouTube, TikTok, and Instagram URLs.

YouTube uses `youtube-transcript-api`. TikTok and Instagram use yt-dlp + faster-whisper.

PyPI: [pypi.org/project/clipscribe](https://pypi.org/project/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 works without cookies. Pass cookies only if the site blocks the anonymous download:

```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. Concurrent calls on one instance are serialized with a lock.
- `register()` is per instance, not global.
- Failures raise `ClipscribeError` subclasses (`UnsupportedURLError`, `TranscriptNotFoundError`, `AuthenticationRequiredError`, ...). `extract_many()` returns a `BatchResult` with `.results` and `.errors`.
- CLI: `clipscribe URL [--save] [--format json,txt,srt]` or `python -m clipscribe URL`.
- Async: `await api.extract_async(url)` and `await api.extract_many_async(urls)`.
- You are responsible for complying with YouTube, TikTok, and Instagram terms of use.
