typed-ffmpeg - Antarmuka Bertipe dan Editor Filter Visual untuk FFmpeg

 (github.com/livingbio)
5 poin oleh GN⁺ 2025-05-31 | 1 komentar | Bagikan ke WhatsApp
  • typed-ffmpeg adalah antarmuka untuk menangani FFmpeg secara type-safe di Python dan TypeScript, menyediakan tipe terperinci dan dokumentasi untuk graph filter yang kompleks
  • Terinspirasi dari ffmpeg-python, tetapi menambahkan fitur seperti autocomplete IDE, pengetikan komprehensif, serialisasi JSON graph filter, dan validasi FFmpeg otomatis
  • v4 menyediakan paket PyPI untuk FFmpeg 5.x hingga 8.x, sementara typed-ffmpeg default memasang binding FFmpeg 8.x terbaru
  • Paket Python berjalan hanya dengan standard library, tetapi visualisasi graph dan parsing CLI masing-masing perlu dipasang sebagai extra opsional [graph] dan [parse]
  • Tersedia Interactive Playground untuk bereksperimen dengan filter dan command di browser serta melihat graph secara real-time, sehingga pembelajaran dan prototyping bisa dilakukan tanpa lingkungan lokal

Antarmuka FFmpeg yang disediakan typed-ffmpeg

  • typed-ffmpeg menyediakan antarmuka modern yang type-safe untuk FFmpeg di Python dan TypeScript
  • Mendukung tipe terperinci dan dokumentasi untuk filter yang kompleks, sekaligus melengkapi keterbatasan umum ffmpeg-python seperti kurangnya integrasi IDE dan tidak adanya pengetikan yang komprehensif
  • Sebagai fitur baru, menyediakan serialisasi JSON graph filter dan validasi FFmpeg otomatis
  • Dokumentasi dapat dilihat di Documentation

Fitur utama

  • Zero Dependencies: hanya terdiri dari standard library Python, sehingga meningkatkan kompatibilitas dan keamanan
  • Menyederhanakan penyusunan graph filter dengan antarmuka Pythonic
  • Mendukung sebagian besar filter FFmpeg secara bawaan dan menyediakan autocomplete IDE
  • Docstring inline memungkinkan referensi langsung cara penggunaan filter
  • Menyediakan pemeriksaan tipe statis dan dinamis untuk meningkatkan keandalan kode dan pengalaman pengembangan
  • Graph filter dapat disimpan dalam format JSON dan dimuat kembali
  • Visualisasi graph dengan graphviz membantu pemahaman dan debugging
  • Menyediakan fitur untuk mengidentifikasi error graph filter dan membantu memperbaikinya
  • Menyediakan antarmuka yang lebih komprehensif, mencakup opsi input/output serta codec dan format tambahan
  • Melalui evaluasi parsial, graph filter dapat disusun secara modular dan digunakan ulang
  • Mendukung analisis file media secara bawaan menggunakan ffprobe dari FFmpeg, serta mengekstrak metadata melalui antarmuka dictionary dan dataclass

Struktur paket berdasarkan versi FFmpeg

  • typed-ffmpeg v4 menyediakan paket PyPI terpisah untuk setiap versi mayor FFmpeg
    • typed-ffmpeg: versi terbaru, 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 bersama dan dipasang otomatis
  • Semua paket mengekspos namespace ffmpeg yang sama, sehingga bentuk kode tetap sama paket versi mana pun yang dipasang
  • Untuk menyesuaikan dengan versi FFmpeg yang terpasang, periksa versinya dengan ffmpeg -version | head -1, lalu pasang paket yang sesuai
  • Struktur paket v4 dapat dilihat di dokumen v4 Package Architecture
  • Saat upgrade dari typed-ffmpeg 3.x, rujuk Migration Guide

Instalasi dan extra opsional

  • Binding FFmpeg 8.x terbaru dipasang dengan perintah berikut
pip install typed-ffmpeg
  • Binding untuk versi FFmpeg tertentu dipasang melalui paket terpisah
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
  • Fitur opsional dipasang sebagai extra
    • [graph]: visualisasi graph berbasis Graphviz
    • [parse]: parsing CLI dan dukungan compile_as_python()
  • Extra [parse] memasang data cache per versi yang diperlukan oleh ffmpeg.compile.compile_cli.parse() untuk merekonstruksi graph filter dari command line FFmpeg, yaitu ffmpeg-data-v5 hingga ffmpeg-data-v8
  • Sebagian besar pengguna tidak memerlukan extra [parse]
  • FFmpeg harus sudah terpasang di sistem
  • Jika harus dipasang bersamaan dengan ffmpeg-python, pasang typed-ffmpeg-compatible untuk menghindari konflik nama modul, lalu gunakan import typed_ffmpeg as ffmpeg

Binding TypeScript dan contoh penggunaan

  • Binding TypeScript adalah fitur eksperimental, dengan paket npm untuk setiap versi mayor FFmpeg
    • @typed-ffmpeg/core: runtime inti untuk Node.js dan ESM browser
    • @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 terbaru dipasang dengan perintah berikut
npm install @typed-ffmpeg/core @typed-ffmpeg/v8
  • API TypeScript mencerminkan API Python, tetapi menggunakan pola idiomatis TypeScript seperti objek opsi alih-alih argumen keyword
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 mencakup bundle CJS, ESM, dan ESM yang aman untuk browser, yang dipilih otomatis melalui field exports
  • Setiap paket versi menyertakan komentar JSDoc yang menunjukkan ketersediaan filter untuk versi FFmpeg tersebut

Alur penggunaan Python dan playground

  • Contoh penggunaan dasar adalah alur menganalisis file media dengan ffmpeg.probe(), lalu membalik input.mp4 secara horizontal dan mengekspornya sebagai output.mp4
  • Contoh yang lebih kompleks menyusun graph filter dengan mengombinasikan trim, concat, overlay, dan drawbox
  • Contoh lebih banyak dapat dilihat di dokumen Usage
  • Interactive Playground menyediakan lingkungan untuk menjalankan typed-ffmpeg langsung di browser
    • Eksperimen filter dan command FFmpeg
    • Visualisasi real-time graph filter
    • Pengujian konfigurasi input/output
    • Belajar melalui contoh interaktif
    • Berbagi graph filter
  • Playground cocok untuk mempelajari dan membuat prototipe chain filter FFmpeg tanpa pengaturan lingkungan lokal

Cara pengembangan dan latar belakang

  • Ide awalnya adalah membuat FFmpeg filter SDK langsung dari dokumentasi FFmpeg menggunakan GPT-3
  • Dalam proses pengembangan, ada keterbatasan untuk mengotomatiskan pekerjaan sepenuhnya hanya dengan GPT-3, sehingga beralih ke pendekatan code generation tradisional untuk menyelesaikan SDK
  • GitHub Copilot dan GPT-3 membantu mempercepat pengembangan dan menghemat waktu
  • Gaya API dan ide desain dari proyek ffmpeg-python memengaruhi pengembangan typed-ffmpeg
  • Dependensi pengembangan dikelola dengan pyproject.toml dan uv.lock, dan lingkungan pengembangan dipasang dengan perintah berikut
uv pip install --group dev

Bacaan terkait

1 komentar

 
GN⁺ 2025-05-31
Komentar Hacker News

  • Semua parser/alat opsi baris perintah pada dasarnya masing-masing adalah bahasa konfigurasi yang lengkap, dan setiap alat seharusnya dipandang sebagai “program/konfigurasi” yang ditulis dalam bahasa itu, tetapi hal ini sering diremehkan
    Karena shell Unix melakukan pemisahan kata sebelum interpretasi akhir argv, banyak dialek terlihat mirip di permukaan, padahal kenyataannya sangat beragam sampai membingungkan
    Dulu saya pernah menjalankan --help dan -h pada semua program di /usr/bin, dan persentase yang tidak memberikan bantuan berguna ternyata cukup tinggi
    Jadi memberi tipe pada alat yang kompleks seperti ffmpeg punya manfaat praktis, sekaligus membantu menampilkan realitas ini dengan lebih jelas

    • Mungkin ini bukan poin utama yang dimaksud, tetapi saya merasa man foo lebih andal dan berguna daripada foo --help atau foo -h
    • Dari sudut pandang pemula, saya penasaran di mana saja benturannya terjadi

  • Menarik dan bagus bahwa proyek ini dikembangkan secara aktif, tetapi tampaknya ada beberapa masalah yang mirip dengan ffmpeg-python
    Sepertinya tidak ada cara untuk menentukan filter tanpa input seperti "color", dan juga tidak tampak cara meneruskan flag ke Popen agar jendela CMD tidak muncul pada aplikasi GUI Windows, seperti subprocess.CREATE_NO_WINDOW
    ffmpeg sendiri masih bisa dijalankan langsung setelah ffmpeg.compile(), tetapi untuk ffprobe yang memakai ffmpeg.probe(), itu tidak mudah dilakukan
    Suntingan: filter sumber bisa diatasi dengan ffmpeg.sources.color. Saya juga penasaran apakah ada cara memakai filter sumber arbitrer, seperti memakai vfilter/afilter untuk filter biasa

  • Jika Anda akan melakukan pemrosesan video berbasis skrip di Python, saya sangat menyarankan langsung memakai Vapoursynth
    Alat ini memang dibuat untuk tujuan itu sejak awal, dirawat secara aktif, komunitas dan perkakasnya juga lumayan bagus, dan tidak terikat pada antarmuka baris perintah ffmpeg
    https://www.vapoursynth.com/

  • typed-ffmpeg menonjolkan “keamanan tipe penuh, autocomplete, validasi” sebagai nilai utama, jadi bisakah dijelaskan kenapa masuk akal jika lebar dan tinggi atau koordinat x/y justru dikirim sebagai string?

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

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

    • Sepertinya karena nilai-nilai itu bukan bilangan bulat, melainkan ekspresi ffmpeg yang dievaluasi menjadi bilangan bulat
      Misalnya dokumentasi ffmpeg punya contoh seperti ini: 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
      Untuk memeriksa tipe-nya dengan benar, sepertinya dibutuhkan semacam DSL

  • Ide yang bagus. Secara pribadi saya menantikan versi TypeScript

    • Saya sempat menyuruh Jules preview membuatnya, dan implementasinya cukup naif
      Ada beberapa pendekatan yang lebih mudah dibaca yang terpikir oleh saya, tetapi mengingat ini dibuat dari prompt yang sangat singkat, hasilnya tidak terlalu buruk
      Kalau penasaran, perubahannya ada di branch ini: https://github.com/matt-hensley/typed-ffmpeg/tree/feature/mu...
    • TypeScript tidak disebut di mana pun

  • Rasanya perlu ada deskripsi baris perintah ffmpeg dalam format yang bisa dibaca mesin agar bisa dihasilkan untuk berbagai bahasa

  • Alat visualnya terlihat sangat hebat. FFMPEG adalah contoh yang sangat terbantu oleh pemrograman modular/visual karena sulit untuk mengetahui semua bagian yang ditawarkannya
    Catatan UX kecil: di Win11/Chrome, saya mengira tombol DEL akan bisa dipakai untuk menghapus node atau edge
    Secara keseluruhan keren

    • Jadi akhirnya sekarang ada sesuatu yang mirip dengan DirectShow GraphEdit milik MS

  • Keren, tetapi saya penasaran apakah ini mendukung koneksi pipa frame di antara keseluruhan perintah
    Bagi saya, dari situlah bentuk-bentuk paling menarik dalam alur FFMpeg mulai terbuka

  • Bagus. Jika Anda ingin mengedit video secara visual, Anda juga bisa mencoba alat yang saya buat: https://newbeelearn.com/tools/videoeditor/
    Alat itu akan menghasilkan perintah ffmpeg