typed-ffmpeg - Giao diện typed cho FFmpeg và trình chỉnh sửa bộ lọc trực quan

 (github.com/livingbio)
5 điểm bởi GN⁺ 2025-05-31 | 1 bình luận | Chia sẻ qua WhatsApp
  • typed-ffmpeg là giao diện an toàn về kiểu cho FFmpeg trong Python và TypeScript, cung cấp kiểu chi tiết và tài liệu cho các filter graph phức tạp
  • Lấy cảm hứng từ ffmpeg-python, nhưng bổ sung các tính năng như tự động hoàn thành trong IDE, khai báo kiểu toàn diện, tuần tự hóa filter graph sang JSON và kiểm chứng FFmpeg tự động
  • v4 cung cấp các gói PyPI theo từng phiên bản FFmpeg 5.x~8.x, còn typed-ffmpeg mặc định sẽ cài binding FFmpeg 8.x mới nhất
  • Gói Python chạy chỉ với thư viện chuẩn, nhưng tính năng trực quan hóa graph và phân tích CLI cần được cài dưới dạng extra tùy chọn [graph], [parse]
  • Có Interactive Playground để thử nghiệm filter và lệnh trong trình duyệt, xem graph theo thời gian thực, giúp học tập và tạo prototype mà không cần môi trường cục bộ

Giao diện FFmpeg mà typed-ffmpeg cung cấp

  • typed-ffmpeg cung cấp giao diện hiện đại, an toàn về kiểu cho FFmpeg trong Python và TypeScript
  • Hỗ trợ kiểu chi tiết và tài liệu cho các bộ lọc phức tạp, đồng thời khắc phục các hạn chế thường thấy ở ffmpeg-python như thiếu tích hợp IDE và thiếu hệ thống kiểu toàn diện
  • Các tính năng mới gồm tuần tự hóa filter graph sang JSON và kiểm chứng FFmpeg tự động
  • Có thể xem tài liệu tại Documentation

Tính năng chính

  • Zero Dependencies: chỉ dùng thư viện chuẩn của Python để tăng khả năng tương thích và bảo mật
  • Giao diện Pythonic giúp đơn giản hóa việc cấu hình filter graph
  • Hỗ trợ sẵn phần lớn bộ lọc FFmpeg và cung cấp tự động hoàn thành trong IDE
  • Có thể tham khảo ngay cách dùng bộ lọc qua docstring nội tuyến
  • Cung cấp kiểm tra kiểu tĩnh và động để cải thiện độ tin cậy của mã và trải nghiệm phát triển
  • Có thể lưu và tải lại filter graph dưới định dạng JSON
  • Trực quan hóa graph bằng graphviz giúp dễ hiểu và gỡ lỗi hơn
  • Cung cấp tính năng hỗ trợ xác định và sửa lỗi trong filter graph
  • Cung cấp giao diện toàn diện hơn, bao gồm tùy chọn đầu vào/đầu ra, codec bổ sung và định dạng
  • Đánh giá từng phần cho phép xây dựng và tái sử dụng filter graph theo mô-đun
  • Hỗ trợ tích hợp phân tích tệp media bằng ffprobe của FFmpeg, trích xuất metadata qua giao diện dictionary và dataclass

Cấu trúc gói theo phiên bản FFmpeg

  • typed-ffmpeg v4 cung cấp các gói PyPI tách riêng theo từng phiên bản chính của FFmpeg
    • typed-ffmpeg: phiên bản mới nhất, binding FFmpeg 8.x
    • typed-ffmpeg-v5: binding FFmpeg 5.x
    • typed-ffmpeg-v6: binding FFmpeg 6.x
    • typed-ffmpeg-v7: binding FFmpeg 7.x
    • typed-ffmpeg-v8: binding FFmpeg 8.x
    • ffmpeg-core: runtime dùng chung, sẽ được cài tự động
  • Tất cả các gói đều cung cấp cùng namespace ffmpeg, nên dù cài gói phiên bản nào thì dạng mã vẫn giống nhau
  • Để khớp với phiên bản FFmpeg đã cài, hãy kiểm tra bằng ffmpeg -version | head -1 rồi cài gói tương ứng
  • Có thể xem cấu trúc gói v4 trong tài liệu v4 Package Architecture
  • Khi nâng cấp từ typed-ffmpeg 3.x, hãy tham khảo Migration Guide

Cài đặt và extra tùy chọn

  • Binding FFmpeg 8.x mới nhất được cài bằng lệnh sau
pip install typed-ffmpeg
  • Binding cho từng phiên bản FFmpeg cụ thể được cài bằng các gói riêng
pip install typed-ffmpeg-v5   # FFmpeg 5.x
pip install typed-ffmpeg-v6   # FFmpeg 6.x
pip install typed-ffmpeg-v7   # FFmpeg 7.x
pip install typed-ffmpeg-v8   # FFmpeg 8.x
  • Các tính năng tùy chọn được cài dưới dạng extra
    • [graph]: trực quan hóa graph dựa trên Graphviz
    • [parse]: phân tích CLI và hỗ trợ compile_as_python()
  • Extra [parse] sẽ cài dữ liệu cache theo phiên bản từ ffmpeg-data-v5 đến ffmpeg-data-v8, cần thiết để ffmpeg.compile.compile_cli.parse() tái dựng filter graph từ dòng lệnh FFmpeg
  • Phần lớn người dùng không cần extra [parse]
  • Hệ thống phải được cài FFmpeg
  • Nếu cần cài cùng lúc với ffmpeg-python, hãy cài typed-ffmpeg-compatible để tránh xung đột tên mô-đun, và dùng import typed_ffmpeg as ffmpeg

Binding TypeScript và ví dụ sử dụng

  • Binding TypeScript là tính năng thử nghiệm và cung cấp các gói npm theo từng phiên bản chính của FFmpeg
    • @typed-ffmpeg/core: runtime lõi cho Node.js và browser ESM
    • @typed-ffmpeg/v5: binding FFmpeg 5.x
    • @typed-ffmpeg/v6: binding FFmpeg 6.x
    • @typed-ffmpeg/v7: binding FFmpeg 7.x
    • @typed-ffmpeg/v8: binding FFmpeg 8.x
  • Binding FFmpeg mới nhất được cài bằng lệnh sau
npm install @typed-ffmpeg/core @typed-ffmpeg/v8
  • API TypeScript phản chiếu API Python, nhưng dùng các mẫu quen thuộc của TypeScript như đối tượng tùy chọn thay cho keyword arguments
import { input } from "@typed-ffmpeg/v8";

const cmd = input("input.mp4")
  .video
  .scale({ w: 1280, h: 720 })
  .output("output.mp4")
  .overwriteOutput()
  .compile();
// => ["-i", "input.mp4", "-filter_complex", "...", "output.mp4"]
  • @typed-ffmpeg/core bao gồm các bundle CJS, ESM và ESM an toàn cho trình duyệt, được tự động chọn qua trường exports
  • Mỗi gói phiên bản đều chứa chú thích JSDoc thể hiện khả năng sẵn có của bộ lọc theo từng phiên bản FFmpeg

Quy trình sử dụng Python và playground

  • Ví dụ sử dụng cơ bản là phân tích tệp media bằng ffmpeg.probe(), sau đó lật ngang input.mp4 và xuất thành output.mp4
  • Các ví dụ phức tạp hơn kết hợp trim, concat, overlay, drawbox để xây dựng filter graph
  • Có thể xem thêm ví dụ trong tài liệu Usage
  • Interactive Playground cung cấp môi trường để chạy thử typed-ffmpeg trực tiếp trong trình duyệt
    • Thử nghiệm filter và lệnh FFmpeg
    • Trực quan hóa filter graph theo thời gian thực
    • Kiểm thử cấu hình đầu vào/đầu ra
    • Học qua ví dụ tương tác
    • Chia sẻ filter graph
  • Playground phù hợp để học và tạo prototype chuỗi bộ lọc FFmpeg mà không cần thiết lập môi trường cục bộ

Cách phát triển và bối cảnh

  • Ý tưởng ban đầu là dùng GPT-3 để trực tiếp sinh SDK bộ lọc FFmpeg từ tài liệu FFmpeg
  • Trong quá trình phát triển, người tạo nhận thấy chỉ dùng GPT-3 thì khó tự động hóa hoàn toàn công việc, nên đã chuyển sang cách tạo mã truyền thống để hoàn thiện SDK
  • GitHub Copilot và GPT-3 đã giúp tăng tốc phát triển và tiết kiệm thời gian
  • Phong cách API và ý tưởng thiết kế của dự án ffmpeg-python đã ảnh hưởng đến quá trình phát triển typed-ffmpeg
  • Các phụ thuộc phát triển được quản lý bằng pyproject.toml và uv.lock, và môi trường phát triển được cài bằng lệnh sau
uv pip install --group dev

Bài viết liên quan

1 bình luận

 
GN⁺ 2025-05-31
Ý kiến trên Hacker News

  • Mọi trình phân tích/công cụ tùy chọn dòng lệnh thực ra đều là một ngôn ngữ cấu hình hoàn chỉnh của riêng nó, và từng công cụ nên được xem như một “chương trình/cấu hình” viết bằng ngôn ngữ đó; điểm này thường bị đánh giá thấp
    Vì shell Unix thực hiện tách từ trước khi diễn giải argv cuối cùng nên vô số phương ngữ trông có vẻ giống nhau ở bề ngoài, nhưng thực tế lại đa dạng đến chóng mặt
    Trước đây tôi từng chạy --help và -h với tất cả chương trình trong /usr/bin, và tỷ lệ không lấy được trợ giúp hữu ích là khá cao
    Vì vậy, việc gắn type cho một công cụ phức tạp như ffmpeg vừa có lợi ích thực tế, vừa giúp phơi bày rõ hơn thực tế này

    • Có lẽ đây không phải ý chính được nhắm tới, nhưng tôi cảm thấy man foo đáng tin cậy và hữu ích hơn foo --help hay foo -h
    • Từ góc nhìn người mới, tôi tò mò không biết đã có xung đột ở đâu

  • Việc nó thú vị và được phát triển tích cực là tốt, nhưng có vẻ có một số vấn đề tương tự ffmpeg-python
    Có vẻ không có cách chỉ định các filter không có đầu vào như "color", và cũng không thấy cách truyền flag cho Popen để tránh hiện cửa sổ CMD trong ứng dụng GUI trên Windows, như subprocess.CREATE_NO_WINDOW
    Với bản thân ffmpeg thì có thể ffmpeg.compile() rồi tự chạy trực tiếp, nhưng với ffprobe dùng ffmpeg.probe() thì khó làm như vậy
    Sửa: filter nguồn đã giải quyết bằng ffmpeg.sources.color. Tôi vẫn tò mò liệu có cách dùng filter nguồn tùy ý giống như dùng vfilter/afilter cho filter thông thường không

  • Nếu định xử lý video bằng script trong Python, tôi rất khuyên nên đi thẳng sang Vapoursynth
    Nó được tạo ra cho đúng mục đích đó ngay từ đầu, được bảo trì tích cực, có cộng đồng và công cụ khá ổn, và không bị ràng buộc vào giao diện dòng lệnh của ffmpeg
    https://www.vapoursynth.com/

  • typed-ffmpeg nêu “an toàn kiểu đầy đủ, tự động hoàn thành, kiểm chứng” làm điểm cốt lõi, vậy có thể giải thích vì sao việc truyền chiều rộng, chiều cao hoặc tọa độ x/y dưới dạng chuỗi lại hợp lý không?

    .drawbox(x="50", y="50", width="120", height="120", color="red", thickness="5")

    Nguồn: https://github.com/livingbio/typed-ffmpeg?tab=readme-ov-file...

    • Có lẽ vì các giá trị đó không phải số nguyên, mà là biểu thức ffmpeg được đánh giá thành số nguyên
      Ví dụ tài liệu ffmpeg có ví dụ như thế này: drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red
      Để kiểm tra kiểu đúng cách có lẽ cần một dạng DSL nào đó

  • Ý tưởng hay. Cá nhân tôi đang mong chờ phiên bản TypeScript

    • Tôi thử giao cho bản xem trước Jules làm, nhưng phần triển khai khá ngây thơ
      Tôi có nghĩ ra vài cách dễ đọc hơn, nhưng xét là được tạo từ một prompt rất ngắn thì cũng không quá tệ
      Nếu tò mò, các thay đổi nằm ở nhánh này: https://github.com/matt-hensley/typed-ffmpeg/tree/feature/mu...
    • TypeScript không được nhắc tới ở đâu cả

  • Có lẽ cần một tài liệu mô tả dòng lệnh ffmpeg ở định dạng máy đọc được để có thể sinh ra cho nhiều ngôn ngữ

  • Công cụ trực quan trông đặc biệt tuyệt. FFMPEG là một ví dụ mà lập trình mô-đun/trực quan có thể thực sự hữu ích, vì rất khó biết hết các mảnh mà nó cung cấp
    Một ghi chú nhỏ về UX: trên Win11/Chrome, tôi đã nghĩ có thể dùng phím DEL để xóa node hoặc edge
    Nhìn chung là rất hay

    • Cuối cùng thì cũng có thứ tương tự DirectShow GraphEdit của MS

  • Hay đấy, nhưng tôi tò mò liệu nó có hỗ trợ kết nối pipe frame giữa các lệnh đầy đủ không
    Cá nhân tôi nghĩ từ điểm đó trở đi, những dạng thú vị nhất trong luồng FFMpeg mới bắt đầu mở ra

  • Tốt. Nếu muốn chỉnh sửa video một cách trực quan, bạn cũng có thể thử công cụ tôi làm: https://newbeelearn.com/tools/videoeditor/
    Nó tạo lệnh ffmpeg