MarkItDown Media-to-Markdown
Một bộ lệnh Terminal mình tự xây trên nền MarkItDown của Microsoft, Tesseract OCR và Whisper. Kéo bất kỳ file hoặc folder vào Terminal, nó chuyển hết sang Markdown sạch và lưu ra Desktop — chạy local, offline, không tốn token AI nào.
Vai trò
Tự thiết kế + tự build, một mình
Loại
Công cụ cá nhân (sẽ phát triển thành app)
Thời gian
Tháng 7/2026 – hiện tại (đang tiếp tục)
Công cụ
MarkItDown, Tesseract, ocrmypdf, Whisper, zsh, Claude
Vấn đề
Khi dùng Claude và các AI khác, ảnh, video, PDF và các file media khác tốn rất nhiều token — và AI không phải lúc nào cũng đọc được nội dung đó tốt.
Trường hợp chính của mình: mình học IT hệ từ xa, tài liệu môn học đến dưới dạng ảnh chụp slide, PDF scan, file Office và file ghi âm bài giảng. Đưa thẳng tất cả vào AI chat vừa chậm vừa tốn kém.
Nhận ra điều gì
Qua tự tìm hiểu và thử nghiệm, mình nhận ra chuyển media sang Markdown trước khi đưa vào AI giúp tiết kiệm token và giúp AI hiểu nội dung tốt hơn.
Và nếu bước chuyển đổi chạy ngay trên máy Mac của mình, nó không tốn một token Claude/AI nào cả. Đây là kinh nghiệm cá nhân từ việc mình tự test, không phải số liệu benchmark đã công bố — nên mình không gắn con số nào vào đây.
Người dùng & giới hạn
- Một người dùng duy nhất: chính mình. Một designer đọc được HTML/CSS nhưng không biết code.
- Chỉ dùng Mac, ngân sách hạn chế — chỉ chọn công cụ miễn phí hoặc rẻ.
- Phải hoạt động bằng cách kéo file/folder thả thẳng vào Terminal.
- Không phụ thuộc vào dịch vụ OCR hay transcription trả phí trên cloud.
Giải pháp
Mỗi việc một lệnh, tất cả khai báo trong một file profile Terminal duy nhất. Kéo file hoặc folder vào Terminal là mọi thứ tự chuyển đổi và lưu ra Desktop.
- Một lệnh riêng cho mỗi loại việc — file thường, PDF scan, một ảnh, folder ảnh, audio/video.
- Một lệnh "folder lẫn lộn" tự phân loại từng file theo định dạng.
- PDF scan tự động chuyển qua bước OCR thay vì ra file trống.
- Kết quả luôn nằm ở một chỗ cố định, dễ nhớ: Desktop.
Placeholder — ảnh chụp lệnh Terminal đang chạy (kéo file vào → kết quả chuyển đổi)
Các quyết định thiết kế
Kéo-thả làm cách nhập liệu
Mình không phải developer, nên việc gõ tay đường dẫn file là thứ đầu tiên cần loại bỏ. Kéo file/folder từ Finder vào Terminal tự điền đường dẫn — không phải gõ tay, không lo gõ sai làm hỏng lệnh.
Mỗi việc một lệnh
Mỗi lệnh chỉ làm đúng một loại chuyển đổi. Một tên lệnh ngắn, rõ nghĩa dễ nhớ và dễ tin tưởng hơn một lệnh nhiều flag mà lần nào cũng phải tra lại.
Một lệnh folder tự phân loại theo định dạng file
Folder môn học thực tế rất lộn xộn — PDF, slide, ảnh và file ghi âm trộn lẫn. Một lệnh tự nhận diện loại từng file và đưa đúng hướng xử lý, nên mình không cần tự sắp xếp file trước khi chuyển đổi.
Chạy lại được giữa chừng
Chuyển một folder lớn có thể mất khá lâu, đặc biệt với OCR hoặc audio. Nếu cần dừng giữa chừng (Ctrl+C), chạy lại đúng lệnh đó sẽ tự bỏ qua file đã xong — nên việc bị gián đoạn không bao giờ có nghĩa là phải làm lại từ đầu.
Kết quả luôn ra Desktop
Một nơi lưu cố định, dễ đoán giúp mình không bao giờ phải đi tìm kết quả. Đó luôn là thứ đầu tiên mình thấy khi chuyển qua Desktop.
Bước dọn file để AI dễ đọc
Bản chuyển đổi thô thường có nhiều nhiễu — khoảng trống nhiều dòng liền, chữ UI của phần quiz còn sót lại, rác do OCR. Một bước dọn riêng loại bỏ những thứ đó để file cuối cùng gọn và AI đọc dễ hơn.
Placeholder — ảnh chụp bảng cheat sheet các lệnh
Những gì học được khi test
MarkItDown không đọc được PDF scan hay ảnh chụp chữ thuần — nó không có OCR tích hợp. Những file đó cần qua bước OCR trước, nếu không kết quả ra file trống hoặc gần như trống.
Mình thử OCR trên một thông báo chính thức dạng scan. Nội dung chính và ngày tháng vẫn đúng, nhưng vài con số bị đọc sai — một số nhà ra 57 thay vì 37, một số khác ra 756 thay vì 736, và một số hiệu văn bản viết tay bị đọc thành ký tự lộn xộn. Cấu trúc bảng, con dấu và chữ viết tay đều bị mất trong quá trình này.
Placeholder — so sánh trước/sau giữa thông báo scan và bản Markdown sau OCR
Quy tắc mình chốt lại: dùng Markdown cho tài liệu học dài, chỉ cần nắm ý chính là đủ. Gửi thẳng PDF gốc cho Claude khi cần đúng số liệu, bảng biểu hoặc con dấu.
Các lần chỉnh sửa
- 01
Terminal mở sai shell
Một đoạn code block Markdown bị dán thẳng vào file profile Terminal, làm hỏng cách Terminal mở lên. Sửa bằng cách cài file đó qua lệnh copy (cp) thay vì dán nội dung trực tiếp vào.
- 02
Ảnh bị sắp xếp 1, 10, 2 thay vì 1, 2, 10
Sắp xếp theo alphabet mặc định làm ảnh chụp slide lộn thứ tự bài giảng. Sửa bằng cách đổi sang sắp xếp theo số, để tên file sắp xếp đúng như con người mong đợi.
- 03
Kết quả OCR thô có nhiều nhiễu
Những file OCR đầu tiên có khoảng trống nhiều dòng liền và còn sót chữ UI của phần quiz lẫn vào nội dung. Đây chính là lý do mình xây riêng lệnh dọn file.
Kết quả
Một folder 46 ảnh chụp bài giảng gộp thành một file Markdown duy nhất, chỉ trong một lần chạy.
Sau bước dọn file, file đó giảm từ 836 dòng xuống 397 dòng — mà vẫn giữ đủ 22 dòng "Đáp án".
TODO(Quang): thêm số liệu thời gian tiết kiệm / mức độ sử dụng khi mình bắt đầu theo dõi.
Bước tiếp theo / hướng đi
Biến công cụ Terminal này thành một app thật — trước là macOS, sau đó là iOS — vẫn giữ nguyên ý tưởng kéo-thả nhưng không cần Terminal nữa.
- Cải thiện độ chính xác OCR tiếng Việt.
- Giữ được cấu trúc bảng cho các form scan, thay vì làm mất nó.
Đây là kế hoạch, chưa phải thứ đã làm xong.
