# Video Context

English | [简体中文](README.zh.md)

**Let your AI assistant summarize videos from YouTube, Bilibili, and Xiaohongshu.**

Send a video link to get a summary, take notes, or ask questions about the video. Xiaohongshu support is experimental.

Video Context connects your assistant to video subtitles and local speech transcription through MCP and an Agent Skill. Your assistant writes the summary; Video Context provides the video content with timestamps.

[Get started](#get-started) · [Usage guide](docs/getting-started.md) · [Downloads](https://github.com/ufoooo2025/video-context/releases/tag/v0.1.0a4)

## See an example

![Illustrated walkthrough: send a video link, retrieve 308 subtitle segments, and read an AI-written summary with timestamps.](docs/assets/example-walkthrough.gif)

An illustrated walkthrough based on a real YouTube subtitle extraction, not an app recording. The summary was prepared by an AI assistant for this example. [Source and timestamp links](docs/assets/example.md).

<details>
<summary>View the static summary example</summary>

![Three summary points with timestamps from Lera Boroditsky’s TED talk.](docs/assets/example-summary.png)

</details>

## What you can do

- **Summarize a video:** ask for the main points and jump back to the relevant timestamps.
- **Ask follow-up questions:** find an explanation or turn a tutorial into study notes.
- **Save the transcript:** export Markdown or JSON and reuse cached results offline.

After setup, try sending your assistant a video link with:

> Summarize this video in three points and include timestamps.

## Supported platforms

| Platform | Support | Notes |
| --- | --- | --- |
| YouTube | Subtitles and local speech transcription | Some videos require login or are restricted by region or platform rules |
| Bilibili (B站) | Subtitles, local speech transcription, and part selection | Choose a specific part for multi-part videos |
| Xiaohongshu (小红书) | Local speech transcription when media is accessible | Experimental; paste the full share link, including its parameters |

Video Context uses subtitles and audio. It does not read diagrams, code, or actions that appear only on screen.

## Choose your AI client

| Client | Setup | Validation |
| --- | --- | --- |
| Codex | Default Windows installer; MCP + Skill registration | Local SDK and Skill checks passed |
| Claude Code | Installer with `-Client claude-code`; registers local MCP | Claude Code 2.1.143 reported Connected in isolated configuration |
| WorkBuddy | Installer with `-Client workbuddy`; import the exported MCP entry | Official stdio format; client UI testing pending |
| Other local MCP clients | `-Client generic`; import the exported entry | Depends on the client |

For example, from PowerShell in the extracted folder:

```powershell
# Claude Code: install and register
powershell -NoProfile -File scripts/install.ps1 -Client claude-code
# WorkBuddy: install and generate the configuration to import
powershell -NoProfile -File scripts/install.ps1 -Client workbuddy
```

For a lighter first try, add `-SubtitlesOnly` to skip the speech model and speech-recognition dependencies. Ask your assistant to use `asr=never`; videos without suitable subtitles will need the full installation. [Client setup details](docs/getting-started.md#client-setup).

## Get started

**Version 0.1.0a4 is a development preview**, primarily tested on Windows. Initial setup requires an internet connection and a few dependencies.

1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/). Python 3.11 or 3.12 is required; uv can provision a compatible version. For automatic Codex setup, make sure the Codex CLI is available. Install Node.js for YouTube extraction.
2. Download **video-context-0.1.0a4-source.zip** from the [release page](https://github.com/ufoooo2025/video-context/releases/tag/v0.1.0a4) and extract it to a folder you plan to keep.
3. Double-click **install.cmd**. It installs dependencies, downloads the small speech model (about 500 MB), and registers the MCP server and Skill with Codex.
4. Reopen Codex and send a video link with your request.

The installer is for Windows. Claude Code registration and WorkBuddy configuration export are also available; see the [usage guide](docs/getting-started.md). macOS and Linux have not yet been tested on real machines. The package is not published on PyPI.

## Use from the terminal

Run these commands in the project folder:

```powershell
uv sync --frozen --no-editable --extra asr --extra mcp
uv run --no-sync video-context setup --download-model
uv run --no-sync video-context "VIDEO_URL"
```

Results are saved under `output/`. For subtitles only, skip model setup and add `--asr never`. Use `--offline` to read an existing transcript from the cache.

## Privacy

Video extraction connects to the source platform. Installation also connects to dependency and model download services. Speech recognition runs locally; Video Context does not upload audio to a transcription service. When connected to an AI assistant, the resulting text is passed to that assistant.

Requests are anonymous by default. Browser sessions are read only when explicitly configured. Do not publish cookies, signed share links, or private transcripts.

## Current limits

- Platform access can change; not every link will work.
- Speech recognition can miss names, technical terms, and accents. Check important quotes against the video.
- Defaults: two hours per video, 256 MiB per download, and one speech transcription job at a time.
- HLS/DASH segmented media and automatic translation are not supported.
- Designed for trusted local use. Do not expose it as a public service accepting arbitrary URLs; see [Security](SECURITY.md).

## Contributing

See [Contributing](CONTRIBUTING.md) for development commands and [Validation](docs/release-checks.md) for what has actually been tested. Documentation uses English as the primary language, with separate translations linked at the top of each page.

## License

[MIT](LICENSE). You may use, modify, and distribute the project, including commercially, while retaining the copyright and license notice. Third-party dependencies, models, and video content retain their own licenses and rights.