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.
