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

Install

Pick the platforms you need, or install all of them:

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:

pip install -e ".[all,dev]"

If TikTok/Instagram downloads start failing, upgrade the extractor stack:

pip install -U yt-dlp imageio-ffmpeg

Usage

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):

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:

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:

result = api.extract(tiktok_url, max_retries=2)

TikTok works without cookies. Pass cookies only if the site blocks the anonymous download:

api = TranscriptExtractor(tiktok_cookies_from_browser="firefox")

Or a Netscape cookies file:

api = TranscriptExtractor(tiktok_cookies="tiktok_cookies.txt")

YouTube proxy (optional):

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:

api = TranscriptExtractor(instagram_cookies_from_browser="firefox")
result = api.extract("https://www.instagram.com/reel/REEL_ID/")

Or a Netscape cookies file:

api = TranscriptExtractor(instagram_cookies="instagram_cookies.txt")

TikTok and Instagram videos longer than 15 minutes are rejected unless you raise or disable the cap:

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.