Metadata-Version: 2.4
Name: vidknot
Version: 0.4.0
Summary: VidkNot — Video Knowledge, Knotted. Convert video links to structured notes with dual-ASR cross-validation correction, and sync to Notion/Obsidian/Feishu/Yuque.
Author: VidkNot Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/suonian/vidknot
Project-URL: Repository, https://github.com/suonian/vidknot
Project-URL: Issues, https://github.com/suonian/vidknot/issues
Keywords: video,transcription,AI,notes,knowledge-base,notion,obsidian,feishu,yuque,markdown
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Natural Language :: English
Classifier: Natural Language :: Chinese (Simplified)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp>=2026.3.17
Requires-Dist: fastapi>=0.136.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: youtube-transcript-api>=0.6.0
Requires-Dist: faster-whisper>=1.0.0
Provides-Extra: feishu
Requires-Dist: feishu-docx>=0.2.7; extra == "feishu"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: ruff>=0.2.0; extra == "dev"
Provides-Extra: all
Requires-Dist: feishu-docx>=0.2.7; extra == "all"
Requires-Dist: pytest>=8.0.0; extra == "all"
Requires-Dist: pytest-asyncio>=0.21; extra == "all"
Requires-Dist: ruff>=0.2.0; extra == "all"
Dynamic: license-file

# VidkNot

VidkNot turns video links into structured knowledge notes. It downloads audio, transcribes speech, generates Markdown notes, and saves them to Obsidian, Feishu, Notion, or Yuque.

[![GitHub Release](https://img.shields.io/github/v/release/suonian/vidknot)](https://github.com/suonian/vidknot/releases)
[![License](https://img.shields.io/github/license/suonian/vidknot.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![Tests](https://img.shields.io/badge/tests-242%20passed-brightgreen)](https://github.com/suonian/vidknot/actions)

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

## 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 | ✅ |
| Xiaohongshu (Image notes) | Image gallery | ✅ 4 bugs fixed in v0.3.3 (still active in v0.4.0) |
| 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 [COOKIE_GUIDE.md](COOKIE_GUIDE.md) for the full capability matrix.

## 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

The current GitHub release is `v0.4.0`. Install from GitHub:

```bash
pip install "vidknot @ git+https://github.com/suonian/vidknot.git@v0.4.0"
```

For development:

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

FFmpeg must be available locally:

```bash
ffmpeg -version
```

## Configuration

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

```bash
SILICONFLOW_API_KEY=your_siliconflow_api_key
OPENAI_API_KEY=your_openai_compatible_api_key

# 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](config.yaml). Dual-ASR correction is enabled by default:

```yaml
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:

```bash
# 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:

```bash
python -m vidknot --mcp
```

FastAPI:

```bash
uvicorn vidknot.api:app --reload
```

Python API:

```python
from vidknot import VideoKnowledgePipeline

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

print(result["markdown"])
```

## Output

VidkNot writes Markdown notes with:

- Video title, source URL, and processing metadata
- Topic and summary
- Structured key points and details
- Important quotes
- Terms and explanations
- Timestamped transcript

## Documentation

| Document | Purpose |
| --- | --- |
| [INSTALL.md](INSTALL.md) | Local installation and environment checks |
| [API_GUIDE.md](API_GUIDE.md) | Third-party API configuration |
| [COOKIE_GUIDE.md](COOKIE_GUIDE.md) | Cookie setup and security |
| [DEPENDENCIES.md](DEPENDENCIES.md) | Direct dependencies |
| [CHANGELOG.md](CHANGELOG.md) | Version history |

## 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

## License

[MIT](LICENSE)
