VidkNot

VidkNot is a general research platform framework (v0.6.12) that extracts knowledge from 11+ self-media platforms (YouTube, Bilibili, Douyin, Xiaohongshu, Kuaishou, TikTok, Twitter/X, Instagram, WeChat Channels, Weibo, Vimeo). It downloads audio, transcribes speech via dual-ASR cross-validation, generates Markdown notes, and saves them to Obsidian, Feishu, Notion, or Yuque. v0.4.0 added pluggable storage backends, an async periodic scheduler, a batch runner, and a credential-leak-proof subscription source loader; v0.5.0 added Standard Agent Skill compliance (SKILL.md + --demo mode + scripts/install.sh); v0.6.0 adds unified retry/timeout configuration, a bundled-FFmpeg optional extra, actionable error hints with a friendly CLI error path, and domestic-mirror install support; v0.6.1 fixes a video-duration formatting crash and localizes marketplace display copy to Chinese; v0.6.2 fully translates SKILL.md into Chinese so the marketplace overview page displays in Chinese; v0.6.3 rewrites the marketplace description in plain, everyday language so non-technical users instantly understand what the tool does; v0.6.4 deepens the documentation: a consolidated anti-pattern section, MCP tool docs aligned with the real implementation, an error-classification quick table, and fully spelled-out platform limitation levels; v0.6.5 multi-source audit fixes: CI fully green again, LICENSE restored to proper MIT detection, and environment-independent f2 tests; v0.6.6 fixes three bugs found by an external agent audit (#8/#9/#10): new fw/fw_file destinations that preserve FasterWhisper timestamp segments, no more FW data loss when dual-ASR correction fails, and standardized temp-subdir naming with path-traversal protection; v0.6.11 cross-platform compatibility fixes after a full Windows end-to-end run — 13 issues including the P0 defect where dual-ASR correction silently failed on Windows, plus a one-command Windows installer (scripts/install.ps1) and a Windows CI matrix; v0.6.12 removes the test suite's dependency on the host environment, so the full CI matrix is green again.

| 中文 | English |

What's new in v0.6.12

Removes a test-suite dependency on the host environment; the full CI matrix is green again. The mmx entry-point resolution introduced in v0.6.11 made some test outcomes depend on whether the machine running them had the mmx CLI installed — green locally (mmx present), red on CI (mmx absent). That dependency is now removed from the tests, and standard-stream normalization is verified in a subprocess with a deliberately non-UTF-8 environment.

All 13 Windows cross-platform compatibility fixes from v0.6.11 are retained. The most significant one: dual-ASR correction silently failed on Windows, because subprocess output was decoded with the local code page (GBK) instead of UTF-8. The pipeline raised no error and still produced notes — it just quietly skipped the cross-validation. Also fixed: Windows reserved device names dropping notes, Chinese garbling in MCP stdio, YouTube forced-audio download failures, and a broken local faster-whisper caused by an unpinned PyAV upper bound. Adds a one-command Windows installer (scripts/install.ps1) and a Windows CI matrix.

Content authorization boundaries and the free-first policy are unchanged.

Use Cases

• Convert courses, interviews, podcasts, and industry videos into searchable notes
• Save useful short-video content into a personal knowledge base
• Expose video-to-note capability to agents through MCP
• Reduce transcription mistakes with dual-ASR cross-validation

Supported Platforms

Platform	Type	Status
YouTube, Vimeo	Long-form video	✅ Stable via yt-dlp
Bilibili	Long-form video	✅ Stable with subtitle/danmaku
Douyin (TikTok China)	Short video	✅ Cookie-based direct fetch + 4-layer fallback
TikTok (International)	Short video	✅ Stable via yt-dlp
Twitter / X	Short video	✅ Stable via yt-dlp
Instagram (Reels)	Short video	✅ Stable via yt-dlp
WeChat Channels (视频号)	Short video	⚠️ Reserved (closed WeChat ecosystem; export via packet-capture tools, then use local batch mode)
Xiaohongshu (Image notes)	Image gallery	✅ 4 bugs fixed in v0.3.3 (still active in v0.6.12)
Xiaohongshu (Video notes)	Short video	✅ Direct-link extraction from __INITIAL_STATE__
Kuaishou, Weibo	Short video	⚠️ Framework ready, depends on yt-dlp support
Any yt-dlp-supported site	Mixed	✅ GenericPlatform fallback

See docs/PLATFORMS.md for the full capability matrix (cookie requirements per platform, duration limits, paid-content criteria).

Capabilities

Capability	Description
Video parsing and download	11 platforms + generic yt-dlp fallback, 4-layer fallback for Douyin
Dual-ASR transcription	SiliconFlow SenseVoice + local faster-whisper correction, enabled by default
Structured notes	Generates topic, summary, key points, details, quotes, terms, and full transcript
Storage targets	Obsidian, Feishu, Notion, Yuque, or Markdown-only output
Agent integration	CLI, FastAPI, MCP, and Python API

Installation

️ Prerequisite: FFmpeg must be available before running VidkNot, otherwise all platforms will fail.

macOS: brew install ffmpeg | Ubuntu: sudo apt install ffmpeg | Windows: winget install Gyan.FFmpeg

Don't want a system FFmpeg? Use the bundled static build (binary ships in the wheel, works offline): pip install "vidknot[bundled-ffmpeg] @ git+https://github.com/suonian/[email protected]"

Environment self-check: python -m vidknot --check-env (prints install commands for anything missing)

The current GitHub release is v0.6.12. Install from GitHub:

pip install "vidknot @ git+https://github.com/suonian/[email protected]"

🇨🇳 Mainland China note: if GitHub is slow, point pip at a domestic mirror for dependency downloads (the git repo itself still needs to be reachable — use a mirror clone or a proxy):

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple \
  "vidknot @ git+https://github.com/suonian/[email protected]"

The Tsinghua mirror also covers overseas dependencies such as yt-dlp and faster-whisper. Local ASR models download from Hugging Face by default; from mainland China set export HF_ENDPOINT=https://hf-mirror.com before the first run.

The one-line scripts/install.sh (macOS / Linux) or scripts/install.ps1 (Windows) auto-detects and switches to the Tsinghua mirror.

For development:

git clone https://github.com/suonian/vidknot.git
cd vidknot
pip install -e ".[all]"

Confirm FFmpeg is available:

ffmpeg -version   # or: python -m vidknot --check-env

Choosing an Interface

VidkNot offers four ways to use it. Pick the one that fits your scenario:

Interface	Best For	Command
CLI	Daily use, batch scripts	python -m vidknot "URL"
Python API	Embedding in your own Python project	from vidknot import VideoKnowledgePipeline
FastAPI	Deploying as a web service	uvicorn vidknot.api:app
MCP	Integrating with AI Agents (Claude, Codex)	python -m vidknot --mcp

Not sure which to use? CLI works for most users — one command, done.

Configuration

Copy .env.example to .env and configure the keys you need:

SiliconFlow offers a free speech recognition model (SenseVoice). Register to get a free API Key. Go to siliconflow.cn, create an account, and generate an API Key in the console — it's free.

SILICONFLOW_API_KEY=your_siliconflow_api_key   # Speech transcription (SiliconFlow free model)
OPENAI_API_KEY=your_openai_compatible_api_key  # Note generation (any OpenAI-compatible service)

# Optional: Feishu
FEISHU_APP_ID=your_feishu_app_id
FEISHU_APP_SECRET=your_feishu_app_secret
FEISHU_FOLDER_TOKEN=your_feishu_folder_token

# Optional: Obsidian
OBSIDIAN_VAULT_PATH=/path/to/obsidian/vault

# Optional: Notion
NOTION_TOKEN=your_notion_token
NOTION_PAGE_ID=your_notion_page_id

# Optional: Yuque
YUQUE_TOKEN=your_yuque_token
YUQUE_LOGIN=your_yuque_login

# Optional: Douyin cookie file
VIDKNOT_DOUYIN_COOKIE_FILE=/path/to/douyin-cookies.txt

Default settings live in config.yaml. Dual-ASR correction is enabled by default:

settings:
  enable_correction: true
  correction_version: v4
faster_whisper:
  model: small
  device: cpu
  compute_type: int8

v4 is the conservative default. v3 makes broader corrections and carries a higher risk of changing valid text.

Usage

CLI:

# Generate a note and save to the default destination, Obsidian
python -m vidknot "https://v.douyin.com/example/"

# Print output only
python -m vidknot "https://v.douyin.com/example/" --destination none

# Save to Feishu
python -m vidknot "https://v.douyin.com/example/" --destination feishu

# Disable dual-ASR correction
python -m vidknot "https://v.douyin.com/example/" --no-correct

# Check local requirements
python -m vidknot --check-env

MCP:

python -m vidknot --mcp

FastAPI:

uvicorn vidknot.api:app --reload

Python API:

from vidknot import VideoKnowledgePipeline

pipeline = VideoKnowledgePipeline(destination="none")
result = pipeline.run("https://v.douyin.com/example/")

print(result["markdown"])

Output

VidkNot generates Markdown notes. Example structure:

# [Video Title]

> Source: https://v.douyin.com/example/
> Processed: 2026-08-24 10:30:00

## Core Topic

This video discusses...

## Key Points

1. **First point**: Details...
2. **Second point**: Details...

## Details / Quotes / Terms / Full Transcript

Includes: video title, source URL, processing metadata, core topic, structured key points, details, important quotes, terms and explanations, and timestamped transcript.

Documentation

Document	Purpose
INSTALL.md	Local installation and environment checks
API_GUIDE.md	Third-party API configuration
COOKIE_GUIDE.md	Cookie setup and security
DEPENDENCIES.md	Direct dependencies
CHANGELOG.md	Version history
docs/PRIVACY.md	Privacy guarantees and credential scanning
docs/CONFIG.md	Environment variable reference
docs/BACKENDS.md	Backend storage configuration
docs/PLATFORMS.md	Platform support matrix + TikHub endpoints
docs/DOUYIN_FALLBACK.md	Douyin 4-layer fallback strategy
docs/EXPERIENCES.md	Field-tested battle scars
docs/EXAMPLES.md	Custom backend / task / batch / source recipes
docs/BEST_PRACTICES.md	Best-practices guide (long videos, ASR tuning, troubleshooting)
docs/FAQ.md	FAQ and anti-patterns (check here first when stuck)
scripts/codex_sample_curator.py	Six-gate check for Codex-quality sample candidates

Security And Compliance

• Do not commit .env, cookie files, or API keys
• Only process video content you are allowed to access and use
• Follow the terms of video platforms, cloud services, and note platforms
• Third-party service availability, pricing, and permissions are controlled by their providers

Contact Author

For project inquiries and discussions, scan the QR code below to add the author on WeChat:

License

This project is licensed under the MIT License.

Permissions

• Commercial use (refers to this tool software itself)
• Modification
• Distribution
• Patent use
• Private use

Conditions

• License and copyright notice required

Limitations

• No liability
• No warranty

Important Notice: This tool is intended for personal learning and research purposes only. The copyright of video content downloaded through this tool belongs to the original creators or platforms. Using downloaded content for commercial purposes may infringe on others' copyrights. Please comply with each platform's Terms of Service and applicable laws. This tool assumes no responsibility for users' behavior.

See the LICENSE file for the full text.