Bạn cần biến một video YouTube thành ghi chú Markdown có cấu trúc cho Obsidian – kèm đầy đủ metadata, chapters, và transcript – chỉ bằng một dòng lệnh, không cần API key? YouTube-to-Markdown cho Obsidian (repo JimmySadek/youtube-fetcher-to-markdown) chính là mảnh ghép còn thiếu cho quy trình tự động hóa ghi chú từ video, giúp developer lẫn marketer xây dựng kho tri thức cá nhân từ YouTube mà không phải làm thủ công.
Thank you for reading this post, don't forget to subscribe!Những điểm chính
- Trích xuất transcript (phụ đề tay lẫn tự động), title, channel, duration, description và chapters từ bất kỳ video YouTube công khai nào, đóng gói thành một file Markdown với YAML frontmatter chuẩn Obsidian.
- Không yêu cầu API key YouTube; chỉ cần Python và một thư viện nhẹ, hoạt động ngay cả khi thiếu yt-dlp nhờ fallback oEmbed API.
- Tự động phát hiện file trùng lặp, đánh dấu nguồn gốc dự án, tên file gồm ngày trích xuất và video ID giúp tra cứu dễ dàng.
- Hỗ trợ xuất ra JSON, SRT hoặc stdout, timestamp từng dòng, chọn ngôn ngữ phụ đề, và tích hợp trực tiếp với Claude Code, Cursor, Windsurf qua chuẩn SKILL.md.
- MIT license, miễn phí hoàn toàn, cài đặt nhanh bằng một lệnh
npx skills add.
YouTube-Fetcher-to-Markdown là gì và nó giải quyết vấn đề gì?
Đây là một skill cho Claude Code (và các agent tương thích) – nhưng thực chất là một script Python độc lập có thể chạy tay. Nhiệm vụ của nó rất đơn giản: bạn đưa vào một URL YouTube, nó trả ra một file Markdown đầy đủ metadata nằm trong ~/yt_transcripts/. File này có YAML frontmatter, tên file gắn ngày tháng và video ID, bên trong chứa tiêu đề, kênh, thời lượng, ngày upload, mô tả video kèm link, chapters và toàn bộ transcript. Nếu bạn đang dùng Obsidian, Logseq hay bất kỳ trình soạn thảo Markdown nào hỗ trợ truy vấn frontmatter (như Dataview), bạn có thể dễ dàng lọc transcript theo channel, ngôn ngữ, ngày trích xuất hay dự án nguồn. Thay vì ngồi copy-paste từng phần từ YouTube hay dùng các công cụ chỉ trả về raw caption, công cụ này đóng gói mọi thứ thành một tài liệu có cấu trúc sẵn sàng cho việc học tập và tra cứu dài hạn.
Thực tế sử dụng cho thấy điểm sáng nằm ở việc không cần API key. Bạn khỏi lo đăng ký Google Cloud, bật YouTube Data API. Chỉ cần pip install youtube-transcript-api requests, và nếu muốn đầy đủ description cùng chapters thì thêm brew install yt-dlp (hoặc pip install yt-dlp). Script tự kiểm tra dependency bằng --check-deps, báo rõ thiếu gì. Nếu không có yt-dlp, nó vẫn lấy được tiêu đề và kênh qua oEmbed API, đảm bảo bạn luôn có transcript. Tôi đã thử với một video hướng dẫn Obsidian của Oddyseas, và file Markdown nhận được sạch sẽ, chapters đúng mốc, mô tả giữ nguyên link gốc – đúng chất một tài liệu tham khảo.
Bạn có thể xem toàn bộ mã nguồn và hướng dẫn tại repository gốc trên GitHub.
Những tính năng nổi bật giúp bạn làm việc hiệu quả hơn
Script không chỉ dừng ở việc lấy transcript suông – nó chú trọng vào bối cảnh và khả năng truy vấn về sau. Từ trải nghiệm thực tế, tôi đánh giá cao ba mảng: metadata đầy đủ, chống trùng lặp thông minh, và tích hợp với hệ sinh thái ghi chú hiện đại.
Metadata phong phú và YAML frontmatter
Mỗi file xuất ra có YAML frontmatter bao gồm title, channel, url, video_id, fetched (ngày bạn chạy tool), source_project (tên thư mục dự án nơi lệnh được gọi, rất hữu ích nếu bạn thu thập transcript cho nhiều dự án khác nhau), language, caption_type (manual hay auto-generated), duration, upload_date, và tags. Nhờ đó, bạn có thể dùng plugin Dataview trong Obsidian để tạo danh sách động: hiển thị mọi transcript từ kênh “Odysseas”, chỉ lấy video dài dưới 20 phút, hoặc liệt kê tất cả video đã thu thập trong tháng. Đây là thứ mà các công cụ extract transcript thô hoàn toàn không làm được.
Phát hiện trùng lặp và theo dõi nguồn
Script kiểm tra video_id trong tên file trước khi tải, nếu đã có file tương ứng nó sẽ cảnh báo và bỏ qua (exit code 3). Bạn có thể ép ghi đè bằng --force. source_project cho biết bạn chạy lệnh từ thư mục dự án nào, giúp phân luồng transcript giữa các workspace mà không sợ lẫn.
Tự động kiểm tra phụ thuộc
Chạy --check-deps để xem ngay thiếu gì. Lúc mới cài, tôi quên requests và nó báo lỗi rõ ràng, không đoán mò. Nếu thiếu yt-dlp, script vẫn hoạt động, chỉ mất description và chapters – vẫn có transcript và metadata cơ bản từ oEmbed. Đây là toán tử an toàn thông minh cho những ai không muốn cài đặt phức tạp.
Hướng dẫn cài đặt và sử dụng cơ bản
Bạn có thể dùng skill thông qua Claude Code hoặc chạy script Python trực tiếp. Tôi khuyến khích dùng CLI nếu bạn muốn kiểm soát hoàn toàn.
Cài đặt qua Claude Code
- Mở terminal, chạy
npx skills add JimmySadek/youtube-fetcher-to-markdown. Skill sẽ được cài vào thư mục cấu hình. - Đảm bảo Python 3.8+ đã có. Cài dependency:
pip install youtube-transcript-api requests. Nếu muốn đầy đủ description:brew install yt-dlp(macOS) hoặcpip install yt-dlp. - Kiểm tra:
python3 ~/.config/skillshare/skills/youtube-fetcher/scripts/fetch_transcript.py --check-deps. - Dùng với Claude: chỉ cần nói “Get me the transcript for [URL YouTube]” – Claude tự gọi skill và lưu file.
Chạy script thủ công
- Clone repo:
git clone https://github.com/JimmySadek/youtube-fetcher-to-markdown.git ~/.config/skillshare/skills/youtube-fetcher - Cài dependency như trên.
- Chạy:
python3 ~/.config/skillshare/skills/youtube-fetcher/scripts/fetch_transcript.py “URL_YouTube”. - File Markdown nằm trong
~/yt_transcripts/với tên dạngYYYY-MM-DD_tieu-de-slug_[videoID].md.
Sau lần đầu thành công, bạn sẽ thấy ngay file có bố cục rõ ràng: phần đầu là metadata dạng bảng, tiếp đến mô tả video, rồi chapters và cuối cùng là transcript. Bạn có thể mở bằng Obsidian, Typora hay bất kỳ editor Markdown nào.
Ai nên dùng và những tình huống chưa phù hợp
Dựa trên trải nghiệm, tôi nhận thấy YouTube-Fetcher-to-Markdown là trợ thủ đắc lực cho người xây dựng second brain, content creator cần trích dẫn nhanh, nhà nghiên cứu muốn lập chỉ mục video học thuật, hoặc ai đang tự động hóa pipeline ghi chú bằng agent. Ngược lại, nếu bạn cần xử lý video không có phụ đề (manual hay auto), hoặc bạn muốn chất lượng transcript cao hơn hẳn so với caption gốc, thì nên kết hợp thêm Whisper để sinh transcript chính xác. Công cụ này cũng không truy cập được video riêng tư hoặc giới hạn độ tuổi. Với những ai chỉ cần caption thô và không quan tâm metadata, các extractor đơn giản khác có thể đủ dùng.
Tuy nhiên, một khi bạn đã nếm trải cảm giác lướt Dataview trong Obsidian và kéo ra danh sách mọi video đã xem với đầy đủ chương và mô tả, bạn sẽ thấy công cụ này đáng giá từng phút cài đặt.
Các tùy chọn nâng cao và mẹo sử dụng
Script đi kèm nhiều flag hữu ích cho phép bạn tùy biến đầu ra theo nhu cầu thực tế. Dưới đây là những tùy chọn tôi thường dùng và cách chúng giải quyết vấn đề cụ thể.
Timestamp từng dòng transcript
Thêm --timestamps (hoặc -t) để mỗi dòng transcript có gắn mốc thời gian dạng [MM:SS]. Cực kỳ tiện khi bạn cần trích dẫn chính xác một đoạn trong video hoặc tạo mục lục nhảy theo thời lượng. Ví dụ: python3 fetch_transcript.py “URL” --timestamps.
Chọn ngôn ngữ phụ đề
Nếu video có phụ đề đa ngôn ngữ, dùng --lang es để lấy tiếng Tây Ban Nha. Hoặc --list để xem danh sách ngôn ngữ có sẵn trước. Lệnh: python3 fetch_transcript.py “URL” --list.
Định dạng xuất JSON hoặc SRT
Với --format srt, bạn có ngay file phụ đề chuẩn SubRip để dùng trong trình phát video. --format json cho ra dữ liệu thô để phân tích bằng script khác. Kết hợp --stdout để in ra terminal thay vì lưu file, hữu ích khi bạn muốn pipe sang công cụ khác.
Ghi đè và kiểm soát đường dẫn
--force bỏ qua kiểm tra trùng, luôn tải mới. --output cho phép chỉ định thư mục hoặc tên file tuỳ ý. --source tên_project giúp bạn đánh dấu transcript thuộc về dự án nào, nhất quán với cách tổ chức thư mục.
Tôi thường dùng --timestamps khi ghi chú podcast, --lang en mặc định, và --source để phân biệt giữa các dự án khách hàng. Những flag này không làm script nặng nề thêm mà mang lại khả năng tuỳ biến cao cho quy trình tự động.
Câu hỏi thường gặp
Tôi có cần API key của YouTube để dùng công cụ này không?
Hoàn toàn không. Script sử dụng youtube-transcript-api để lấy phụ đề và yt-dlp hoặc oEmbed API để lấy metadata, tất cả đều không yêu cầu xác thực. Bạn chỉ cần Python và các gói pip, không cần đăng ký Google Cloud.
Nếu video không có phụ đề thì sao?
Công cụ báo lỗi và không tạo được file. Đây là giới hạn cốt lõi vì nó dựa vào caption từ YouTube. Với video không có caption (dù auto-generated cũng không có), bạn nên cân nhắc dùng Whisper hoặc dịch vụ nhận dạng giọng nói khác để tạo transcript, rồi tự đóng gói thành Markdown thủ công hoặc kết hợp với script này cho phần metadata.
Tôi có thể dùng công cụ này trên Windows không?
Có. Chỉ cần cài Python 3.8+ (thêm vào PATH) và pip install các dependency như trên. Thao tác cài yt-dlp qua pip (không cần brew). Đường dẫn script sẽ khác đôi chút, nhưng mọi chức năng hoạt động bình thường. SKILL.MD cũng hoạt động với Claude Code trên Windows.
Tôi muốn tích hợp vào pipeline CI/CD, có hỗ trợ gì không?
Exit code được định nghĩa rõ ràng: 0 thành công, 1 lỗi, 2 thiếu dependency, 3 trùng lặp. Bạn có thể dùng --force, --stdout, --format json và --output để lấy đầu ra có cấu trúc và đưa vào CI job một cách đáng tin cậy. Không cần biến môi trường đặc biệt.
Tôi đang dùng Obsidian Dataview, file tạo ra có tương thích ngay không?
Có. YAML frontmatter được canh chuẩn, bao gồm các trường như title, channel, language, upload_date, duration… Bạn chỉ cần đặt thư mục ~/yt_transcripts/ (hoặc link) vào vault, Dataview sẽ nhận diện. Sau đó bạn có thể viết query kiểu dv.list(dv.pages('"yt_transcripts"').file.link) để duyệt.
Kết luận
YouTube-Fetcher-to-Markdown là một món vũ khí nhỏ gọn nhưng sắc bén cho bất kỳ ai muốn đưa tri thức từ YouTube vào kho ghi chú cá nhân một cách có hệ thống. Không cần API key, metadata đầy đủ, chống trùng, tương thích Obsidian ngay lập tức – nó lấp đầy khoảng trống mà các transcript extractor khác bỏ quên. Nếu bạn đang dành hàng giờ mỗi tuần để xem video và ghi chú bằng tay, hãy cài ngay và chạy thử vài video. Chỉ mất 5 phút cài đặt, còn lại là sự tự động hoá nhẹ nhàng. Ghé repo chính thức để cập nhật phiên bản mới nhất và đóng góp nếu bạn muốn.
