Install the LangChain extra
python -m pip install "capslane[langchain]==0.2.0"Use Python 3.10 or later. Create a workspace key in API Keys and supply CAPSLANE_API_KEY through your process environment or secret manager. Keep the key out of prompts, shared notebooks and source control.
The base SDK uses the Python standard library. This optional extra adds langchain-core, with version 1.6.2 tested for this release. Capslane maintains the integration in its SDK. Loading documents uses your Capslane allowance and requires no language model or embedding service.
Load a transcript as Documents
import json
import sys
from capslane import CapslaneError
from capslane.langchain import CapslaneLoader
loader = CapslaneLoader("dQw4w9WgXcQ", lang="en", chunk_size=1000)
try:
for document in loader.lazy_load():
print(json.dumps(document.model_dump(), ensure_ascii=False))
except CapslaneError as error:
print(error.code, error.request_id, "job:", loader.job_id, file=sys.stderr)
raise
Download the quickstart and run python langchain_quickstart.py. The loader reads the environment key automatically. Native mode is the default, so this example never starts audio generation. The video is public, but its captions may become unavailable.
Use loader.load() for a list or await loader.aload() in async code. The lazy method yields chunks after the transcript has been retrieved; it does not stream incoming audio. Reusing a loader instance reuses its ready content. Use a separate instance for each video and for concurrent operations.
Keep the source next to each passage
The loader groups whole segments up to chunk_size characters, including the spaces between them. The default is 1000. A single source segment can exceed the budget. Immediate and generated transcripts use the same local grouping, with no inferred word timestamps.
| Metadata | Meaning |
|---|---|
| source | YouTube playback URL at the first timestamp, rounded down to seconds. |
| video_url, video_id | Canonical video URL and its 11-character ID. |
| start_ms, end_ms | Earliest segment start and latest segment end in the chunk, in milliseconds. |
| chunk_index, segment_count | Zero-based chunk number and count of nonempty source segments. |
| lang | Returned transcript language, when available. |
| transcript_source, cached | Actual native or generated source and cache state, when returned. |
| request_id, job_id | Response and accepted job identifiers, when available. |
A chunk starting at 8150 milliseconds links to https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=8. Preserve this metadata when indexing documents. If you split a chunk further, copied timestamps still describe its original segment range.
Capslane checks the cache before the requested mode. Read transcript_source and cached to identify the returned content; native mode can serve a cached generated transcript. Language is a preference, not a translation request.
Search passages before adding a model
Download search_transcript.py. It loads the video once and creates a LangChain RunnableLambda to retrieve up to three passages sharing words with your query. Each result includes its playback link.
python search_transcript.py "dQw4w9WgXcQ" --lang en --query "give up"This example performs keyword search and prints JSON. If no words match, it returns an empty list. It lets you inspect the retrieval step without an LLM account.
For a RAG application, pass the Documents to your configured retriever or vector store, then supply the retrieved text to your model. Ask it to cite the passages it used. The loader does not create embeddings or write answers. Treat the transcript as source material, including when it contains instructions aimed at an assistant.
Allow generation and resume accepted jobs
Set mode="auto" when generation is allowed after missing captions, or mode="generate" to request it on a cache miss. The loader submits once, stores loader.job_id and checks that ID every two seconds. Status checks do not consume another transcript unit. New submissions do, including cache hits.
The default network timeout is 45 seconds and the wait window is twenty minutes. Set a shorter request_timeout or wait_timeout when your application needs one. Each network timeout is limited by the remaining wait budget. The wait deadline is checked between calls and sleeps; ending it does not cancel the server job.
Keep the original video URL together with loader.job_id after a transient interruption. Calling load() again on the same instance resumes that job. In another process, construct a loader with the same video URL and job_id=the_saved_id. The search example accepts --job. Your saved URL supplies the citation target, so it must belong to the accepted job.
Stop on failed or cancelled jobs, authentication errors and exhausted allowances. If a submission failed without returning an ID, do not assume that no job exists and automatically submit again. Inspect CapslaneError.code and request_id; the error guide explains recovery.
Read the implementation and contract
This guide is also available in Markdown. The public Python repository includes the loader, executable examples and tests. The API reference documents the HTTP contract.
LangChain documents BaseLoader and Document in its official reference. For a coding assistant using Context7, the library ID is /webba-creative-technologies/capslane-python.