install-by2kb

by2kb

Forward a video. Keep the knowledge.

by2kb turns a video URL into three durable Markdown artifacts in your own knowledge base: the evidence-preserving transcript, a short “is this worth reading?” abstract, and long-form study notes.

The primary user is an agent user. Send a Bilibili URL or media attachment to an agent such as Hermes; by2kb handles media retrieval and the selected local or cloud ASR provider, while the agent uses its existing model authentication to produce both summaries. Standalone users can run the same pipeline with their own OpenAI-compatible API key.

See it in action

Copy a video link. Send it to Hermes. Keep the knowledge.

https://github.com/user-attachments/assets/834f9e97-46f5-42a3-aeb4-66ee1a7f1020

19-second demo: Bilibili → Hermes on Telegram → knowledge notes. Chinese-language example; processing waits have been cut for brevity, not shown in real time. Sound optional.

Latest release. Agent-guided installation, a cloud-free local Whisper default, upgrade-safe personalization, Bilibili/YouTube ingestion, Agent/API enrichment, task control, and the Hermes plugin are implemented. A resident service, native Telegram/Lark bots, and remote knowledge-base sinks remain planned.

Start here

Requires Python 3.12+, pipx, and ffmpeg/ffprobe on PATH.

Ask your Agent to install it

Send this prompt to an Agent with terminal access:

Read and follow the official by2kb installation skill:
https://raw.githubusercontent.com/Charlesmpc/by2kb/main/skills/install-by2kb/SKILL.md

The installation Skill defaults to local faster-whisper, Agent-hosted summaries, Bilibili and YouTube sources, and a local Markdown knowledge base. It does not clone the repository or ask for cloud credentials in chat.

Upgrades replace application and adapter code but preserve $BY2KB_HOME (normally ~/.by2kb), the configured knowledge-base folder, downloaded models, job history, credentials, and custom Skills. See Upgrading.

Install it yourself

Install the published package with local Whisper and YouTube support:

pipx install "by2kb[asr-whisper,youtube]"
by2kb init --preset agent-local
by2kb models install

Cloud Doubao ASR remains available for machines that should not run Whisper locally:

pipx install "by2kb[asr-doubao,youtube]"
by2kb init

by2kb init guides you through four decisions:

1. where the local knowledge base should live;
2. whether transcription uses local faster-whisper or cloud Doubao AUC;
3. local model settings, or the private TOS bucket and Doubao credentials;
4. whether summaries run in an agent (agent), through a standalone LLM API (api), or remain disabled.

After installing the selected optional ASR runtime/model, verify the deployment:

by2kb doctor
by2kb doctor --json

Bilibili and YouTube are enabled by default, and yt-dlp ships with the base package. YouTube uses available captions first, then the configured ASR when audio is needed. No separate platform configuration is required. Explicit source overrides remain respected; see upgrading source defaults if an older configuration deliberately or historically lists only Bilibili.

Agent-first: Hermes

After selecting agent during initialization:

by2kb agent install hermes
hermes gateway restart

These commands are for the legacy copy-based adapter installation. If Hermes already manages your by2kb plugin through Git or the catalog, do not reinstall it with the copy installer. See native plugin setup and upgrade ownership. Catalog submission is pending.

Now an authorized user can send a Bilibili, b23.tv, YouTube, or youtu.be URL to the Telegram Hermes bot. The plugin acknowledges immediately, runs transcription in the background, calls the Hermes host model through bounded staged operations, writes all three artifacts, and replies with the short abstract and knowledge-base paths. No MCP server and no separate by2kb LLM key are required.

Standalone

Select api during initialization, provide an OpenAI-compatible endpoint, model and API key, then run:

by2kb ingest "https://www.bilibili.com/video/<bvid>/"
by2kb ingest ./meeting.mp3
by2kb ingest ./lecture.mp4

See Agent integration for the reusable staged ingest → next → submit enrichment contract used by other agent hosts. See Agent task control for the versioned status/wait/cancel/retry protocol and checkpoint-aware retries. See ASR providers for optional local faster-whisper setup, explicit model installation, and the existing cloud Doubao path. Bilibili HTTP 412? Version 0.5.0 can recover from a blocked view request using pagelist to obtain CID and continue native audio acquisition—no browser required. An opt-in browser Plan B uses a dedicated Chromium session when native acquisition fails. It requires the browser extra and manual login when the site requests it; neither route guarantees recovery from all site risk controls. See the browser setup and fallback guide.

See Source providers for configurable provider priority, default yt-dlp routing, caption policy, audio fallback, and cookie handling. See Local media for supported formats, content-addressed deduplication, ffmpeg requirements, and attachment handling. See Diagnostics for every read-only check and the Agent-facing JSON schema. See Transcript quality for deterministic enrichment gates, recorded metrics, and warning behavior. See Long-form enrichment for segment-safe planning, intermediate caching, recursive reduction, and provenance. See Agent enrichment provider for the bounded callback protocol and API-key versus subscription/OAuth authentication tradeoffs.

The name can be read as B/Y to KB — Bilibili and YouTube to Knowledge Base — while the architecture is intended to support more video sources over time.

Why

Most video tools optimize for watching, summarizing, or taking notes inside a browser. That is useful, but it is not the workflow this project wants:

• Interesting videos are often discovered in a mobile app.
• A browser extension should not be required to keep a desktop computer online.
• The transcript should become a portable artifact, not remain in extension storage.
• The original transcript and AI-edited output should be kept separately.
• Summarization should follow the user's own methods, prompts, and domain knowledge.
• Markdown and source JSON should remain the source of truth; a vector database is only an optional index.

There is also an obvious alternative that this project deliberately does not take as the primary path: sending the video itself to a multimodal bot. In practice it hits two walls:

• Access. Bots are usually locked out of the watch page — platforms gate playback behind logins and anti-scraping, and generally only allow metadata-level access. The same gating is exactly why subtitle and metadata APIs remain the most reliable entry point.
• Cost. Even when the content is reachable, feeding video into a model consumes orders of magnitude more tokens than working with text.

So by2kb works down a cost ladder, from lightest to heaviest:

1. Native transcript — if subtitles exist, the job is nearly free: metadata-level access is enough and the payload is small text.
2. Audio stream + ASR — when there are no subtitles, retrieve the audio track and transcribe it.
3. Full media download — whe