zegplayer

<div align="center"> # 🎬 Zegplayer **Turn any video into timestamped, AI-generated notes — entirely on your machine.** A local-first, privacy-respecting desktop app that transcribes any video locally and lets your own AI agents write timestamped notes about what's on screen. Great for studying, research, meetings, lectures, tutorials, or reviewing anything you watch. [](LICENSE) [](docs/wiki/Platform-Support.md)        [](https://github.com/megz2020/zegplayer/stargazers) [](https://github.com/megz2020/zegplayer/issues) [](CONTRIBUTING.md) </div> --- Zegplayer loads a video — a local file or a YouTube URL — transcribes its audio **locally** with `whisper-cli`, and has installed AI CLI agents (Claude Code, Codex, OpenCode) or local HTTP model servers (LM Studio, Ollama) generate timestamped notes about what's on screen. Export your notes (for example, as Markdown for Obsidian), and let your AI agents query your transcripts and notes through a built-in **read-only MCP server**. Everything runs on your machine. The app itself never uploads your video or audio anywhere — all AI calls go through whatever CLI or local model server you have configured. **[⬇ Download the latest release](https://github.com/megz2020/zegplayer/releases/latest)** — macOS (`.dmg`), Windows (`.exe`), Linux (`.AppImage` / `.deb`). See [Install](#install) for first-launch steps, and [Requirements](#requirements) for the tools you'll need on your `PATH`. ## How it works ```mermaid flowchart LR A[📹 Local file<br/>or YouTube URL] --> B[ffmpeg<br/>extract audio] B --> C[whisper-cli<br/>local transcription] C --> D[(SQLite<br/>transcript + frames)] D --> E{Your AI<br/>agent} E -->|CLI: claude / codex / opencode| F[📝 Timestamped notes] E -->|local server: LM Studio / Ollama| F F --> G[📤 Export<br/>Markdown / Obsidian / Logseq] F --> H[🔌 Read-only MCP<br/>agents query your data] style A fill:#2d6cdf,color:#fff style C fill:#0e8a16,color:#fff style F fill:#d4a017,color:#fff style D fill:#6f42c1,color:#fff ``` Nothing in this pipeline leaves your machine: transcription is local, the database is local, and AI calls go to whatever agent/model server *you* run. ## Features - **Load any video** — open a local video file or paste a YouTube URL. - **Local transcription** — audio is transcribed on your machine with `whisper-cli` (whisper.cpp). No cloud transcription service. - **AI-generated notes** — generate timestamped notes about what's on screen using installed AI CLI agents (Claude Code, Codex, OpenCode) or local HTTP model servers (LM Studio, Ollama). - **Export your notes** — export to formats such as Markdown, ready for tools like Obsidian and Logseq. - **Read-only MCP server** — exposes your video transcripts and notes so the same AI agents can query them. - **Local-first & private** — your data lives in a local SQLite database; the app does not upload video or audio. - **Cross-platform** — macOS (Apple Silicon) and Windows x64 today; Linux runs with [some known gaps](docs/wiki/Platform-Support.md). ## Architecture ```mermaid flowchart TB subgraph UI[" "] R[Renderer<br/>vanilla TS + template HTML] end subgraph Bridge[" "] P[Preload<br/>contextBridge · typed DesktopApi] end subgraph Core[" "] M[Main process<br/>lifecycle · jobs · tooling] end R <-->|IPC| P P <-->|ipcMain.handle| M M -->|spawn| T[ffmpeg · whisper-cli · yt-dlp<br/>AI CLIs · model servers] M --> S[(SQLite<br/>better-sqlite3)] S -.read-only.-> MCP[MCP server<br/>agents query transcripts/notes] style R fill:#2d6cdf,color:#fff style M fill:#0e8a16,color:#fff style S fill:#6f42c1,color:#fff style MCP fill:#d4a017,color:#fff ``` - **Main process** — application lifecycle, window management, and orchestration of the external tools (`ffmpeg`, `whisper-cli`, `yt-dlp`, AI CLIs/model servers). - **Preload** — the secure bridge that exposes a constrained API to the renderer. - **Renderer** — the UI where you load videos, view transcripts, and manage notes. - **MCP server** — a separate process exposing a read-only Model Context Protocol server ([@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol), with `zod` for schema validation) so AI agents can query your data. - **SQLite store** — local persistence via `better-sqlite3`. See the **[wiki](docs/wiki/Home.md)** for a deeper dive: [Architecture](docs/wiki/Architecture.md) · [Connected Services](docs/wiki/Connected-Services.md) · [MCP Server](docs/wiki/MCP-Server.md) · [Platform Support](docs/wiki/Platform-Support.md) · [Troubleshooting](docs/wiki/Troubleshooting.md). ## Requirements Zegplayer shells out to a few external command-line tools that you must install separately. Make sure they are available on your `PATH`. | Tool | Purpose | | --- | --- | | `ffmpeg` / `ffprobe` | Audio/video processing and inspection | | `whisper-cli` | Local transcription (from [whisper.cpp](https://github.com/ggerganov/whisper.cpp)) | | `yt-dlp` | Loading videos from YouTube URLs | | An AI CLI **or** local model server | At least one of `claude` / `codex` / `opencode`, **or** a local model server like LM Studio / Ollama | ### Install hints **macOS** ```bash brew install ffmpeg yt-dlp brew install whisper-cpp # provides whisper-cli ``` Then install at least one AI CLI (`claude`, `codex`, or `opencode`) or run a local model server (LM Studio / Ollama). **Windows** Only `ffmpeg` needs to come from you — Zegplayer auto-downloads `yt-dlp.exe` and `whisper-cli.exe` into its data directory on first launch. For `ffmpeg`: ```powershell winget install Gyan.FFmpeg # or, with scoop: scoop install ffmpeg # or, with chocolatey: choco install ffmpeg ``` Install at least one AI CLI or a local model server. If you already have Python's `openai-whisper` installed (`pip install -U openai-whisper`), the app will use it as a fallback when `whisper-cli` isn't around — but whisper.cpp is preferred (4-5× faster on CPU) and the auto-installer will fetch it regardless. If your machine runs an antivirus that intercepts HTTPS (AVG, Avast, Kaspersky, ESET, corporate proxies), `yt-dlp`'s built-in `certifi` bundle won't trust the intercepting cert. Zegplayer handles this automatically by passing `--no-check-certificates` to yt-dlp on Windows. **Linux** Use your distribution's package manager: ```bash # Debian / Ubuntu sudo apt install ffmpeg sudo apt install yt-dlp # or: pipx install yt-dlp ``` Build or download `whisper-cli` from [whisper.cpp](https://github.com/ggerganov/whisper.cpp). Install at least one AI CLI or a local model server. ## Install Prebuilt installers for macOS, Windows, and Linux are published on the [GitHub Releases](../../releases) page. Download the installer for your platform and run it. > **Note:** The released apps are **unsigned**. You will need to bypass your operating system's security gate the first time you open the app. **First launch on Windows automatically downloads** `yt-dlp.exe` and `whisper-cli.exe` into `%APPDATA%\Zegplayer\bin\`. You don't need to install those yourself. You do still need `ffmpeg` on PATH — the auto-installer skips it because it's much larger. **macOS — bypass Gatekeeper** Either right-click the app and choose **Open** (then confirm), or remove the quarantine attribute: ```bash xattr -dr com.apple.quarantine "/Applications/Zegplayer.app" ``` **Windows — bypass SmartScreen** When SmartScreen appears, click **More info → Run anyway**. ## Build from source ```bash git clone https://github.com/megz2020/zegplayer.git cd zegplayer npm install # installs deps; postinstall rebuilds better-sqlite3 for Electron npm run dev # run the app in development ``` To produce a distributable installer for your current OS: ```bash npm run package:mac # macOS npm run package:win # Windows npm run package:linux # Linux ``` > Each `package:*` script must be run **on** the matching OS (or via CI). Native modules such as `better-sqlite3` cannot be cross-compiled. ## Connecting the MCP server The app ships a **read-only MCP server** that lets your AI agents query your video transcripts and notes. 1. Pick your AI agent in the app. 2. Click **Connect MCP**. That single click registers the read-only MCP server with your chosen agent (`claude`, `codex`, or `opencode`). The agent can then read your transcripts and notes — it cannot modify them. See the [MCP Server wiki page](docs/wiki/MCP-Server.md) for details. ## Development ```bash npm install # install dependencies npm run dev # start the app in development mode npm run check # typecheck with tsc npm test # run the vitest test suite npm run build # build renderer/main and bundle the MCP server ``` See [CONTRIBUTING.md](CONTRIBUTING.md) for project conventions and the contribution workflow. ## Versioning This project follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`). All notable changes are recorded in [CHANGELOG.md](CHANGELOG.md), which follows the [Keep a Changelog](https://keepachangelog.com/) format. Releases are cut by bumping the version and pushing a matching tag: ```bash npm version patch # or: minor / major — updates package.json and creates a vX.Y.Z tag git push --follow-tags ``` Pushing a `v*` tag triggers the CI workflow, which builds the macOS/Windows/Linux installers and drafts a GitHub Release with them attached. ## Contributing Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md) before opening an issue or pull request. The [next-phase roadmap](https://github.com/megz2020/zegplayer/milestones) lives in the issue tracker. ## License This project is **source-available and noncommercial**. It is licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE) — you may use, modify, and share it freely for any **noncommercial** purpose, but **commercial use requires the author's prior approval**. © 2026 Zegplayer contributors