typed-ffmpeg - FFmpeg için tipli arayüz ve görsel filtre editörü

 (github.com/livingbio)
5 puan yazan GN⁺ 2025-05-31 | 1 yorum | WhatsApp'ta paylaş
  • typed-ffmpeg, Python ve TypeScript’te FFmpeg’i tip güvenli şekilde kullanmaya yarayan bir arayüzdür; karmaşık filtre grafikleri için ayrıntılı tipler ve dokümantasyon sağlar
  • ffmpeg-pythondan ilham alır, ancak IDE otomatik tamamlama, kapsamlı tipleme, filtre grafiği JSON serileştirme ve otomatik FFmpeg doğrulaması gibi özellikler ekler
  • v4, FFmpeg 5.x~8.x için ayrı PyPI paketleri sunar; varsayılan typed-ffmpeg en yeni FFmpeg 8.x binding’lerini kurar
  • Python paketi yalnızca standart kütüphaneyle çalışır, ancak grafik görselleştirme ve CLI ayrıştırma için sırasıyla [graph] ve [parse] opsiyonel extra olarak kurulmalıdır
  • Tarayıcıda filtreleri ve komutları denemeyi, grafiği gerçek zamanlı görmeyi sağlayan Interactive Playground sunulur; böylece yerel ortam olmadan öğrenme ve prototipleme yapılabilir

typed-ffmpeg’in sunduğu FFmpeg arayüzü

  • typed-ffmpeg, FFmpeg için modern ve tip güvenli bir arayüzü Python ve TypeScript’e sunar
  • Karmaşık filtreler için ayrıntılı tipleri ve dokümantasyonu destekler; ffmpeg-pythonın yaygın sınırları olarak görülen IDE entegrasyonu eksikliği ve kapsamlı tiplerin yokluğunu tamamlar
  • Yeni özellikler olarak filtre grafiği JSON serileştirme ve otomatik FFmpeg doğrulaması sağlar
  • Dokümantasyona Documentation üzerinden erişilebilir

Başlıca özellikler

  • Zero Dependencies: Yalnızca Python standart kütüphanesiyle oluşturulmuştur; uyumluluğu ve güvenliği artırır
  • Pythonic arayüz ile filtre grafiği oluşturmayı basitleştirir
  • FFmpeg filtrelerinin çoğunu yerleşik olarak destekler ve IDE otomatik tamamlama sağlar
  • Satır içi docstring’lerle filtre kullanımını doğrudan referans almayı sağlar
  • Statik ve dinamik tip denetimi sunarak kod güvenilirliğini ve geliştirme deneyimini iyileştirir
  • Filtre grafiklerini JSON biçiminde kaydedip yeniden yükleyebilir
  • graphviz kullanan grafik görselleştirme, anlamayı ve hata ayıklamayı kolaylaştırır
  • Filtre grafiği hatalarını belirleme ve düzeltmeye yardımcı olma özellikleri sağlar
  • Girdi/çıktı seçenekleri, ek codec’ler ve formatları içeren daha kapsamlı bir arayüz sunar
  • Kısmi değerlendirme sayesinde filtre grafiklerini modüler biçimde oluşturup yeniden kullanmayı sağlar
  • FFmpeg’in ffprobe aracıyla medya dosyası analizine yerleşik destek verir; sözlük ve dataclass arayüzleriyle metadata çıkarır

FFmpeg sürümlerine göre paket yapısı

  • typed-ffmpeg v4, FFmpeg ana sürümlerine göre ayrı PyPI paketleri sunar
    • typed-ffmpeg: En yeni sürüm, FFmpeg 8.x binding’leri
    • typed-ffmpeg-v5: FFmpeg 5.x binding’leri
    • typed-ffmpeg-v6: FFmpeg 6.x binding’leri
    • typed-ffmpeg-v7: FFmpeg 7.x binding’leri
    • typed-ffmpeg-v8: FFmpeg 8.x binding’leri
    • ffmpeg-core: Paylaşılan runtime’dır ve otomatik kurulur
  • Tüm paketler aynı ffmpeg namespace’ini dışa açtığından, hangi sürüm paketi kurulursa kurulsun kod biçimi aynıdır
  • Kurulu FFmpeg sürümüne eşleştirmek için ffmpeg -version | head -1 ile sürümü kontrol edip karşılık gelen paketi kurun
  • v4 paket yapısı v4 Package Architecture dokümanında görülebilir
  • typed-ffmpeg 3.x’ten yükseltirken Migration Guide dokümanına bakın

Kurulum ve opsiyonel extra’lar

  • En yeni FFmpeg 8.x binding’leri şu komutla kurulur
pip install typed-ffmpeg
  • Belirli bir FFmpeg sürümü için binding’ler ayrı paket olarak kurulur
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
  • Seçili özellikler extra olarak kurulur
    • [graph]: Graphviz tabanlı grafik görselleştirme
    • [parse]: CLI ayrıştırma ve compile_as_python() desteği
  • [parse] extra’sı, ffmpeg.compile.compile_cli.parse()ın FFmpeg komut satırından filtre grafiğini yeniden oluşturması için gereken sürüme özel önbellek verileri ffmpeg-data-v5ten ffmpeg-data-v8e kadar olan paketleri kurar
  • Çoğu kullanıcı için [parse] extra’sı gerekmez
  • Sistemde FFmpeg kurulu olmalıdır
  • ffmpeg-python ile aynı anda kurulması gerekiyorsa modül adı çakışmasını önlemek için typed-ffmpeg-compatible kurun ve import typed_ffmpeg as ffmpeg kullanın

TypeScript binding’leri ve kullanım örneği

  • TypeScript binding’leri deneysel bir özelliktir; FFmpeg ana sürümlerine göre npm paketleri sunar
    • @typed-ffmpeg/core: Node.js ve tarayıcı ESM için çekirdek runtime
    • @typed-ffmpeg/v5: FFmpeg 5.x binding’leri
    • @typed-ffmpeg/v6: FFmpeg 6.x binding’leri
    • @typed-ffmpeg/v7: FFmpeg 7.x binding’leri
    • @typed-ffmpeg/v8: FFmpeg 8.x binding’leri
  • En yeni FFmpeg binding’leri şu komutla kurulur
npm install @typed-ffmpeg/core @typed-ffmpeg/v8
  • TypeScript API, Python API’sini yansıtır; ancak anahtar kelime argümanları yerine options object gibi TypeScript’e özgü kalıpları kullanır
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, CJS, ESM ve tarayıcı güvenli ESM bundle’larını içerir; exports alanı üzerinden otomatik seçilir
  • Her sürüm paketi, FFmpeg sürümüne göre filtre kullanılabilirliğini gösteren JSDoc yorumları içerir

Python kullanım akışı ve playground

  • Temel kullanım örneği, ffmpeg.probe() ile medya dosyasını analiz edip input.mp4 dosyasını yatay çevirerek output.mp4 olarak çıktı alma akışıdır
  • Karmaşık örnekler trim, concat, overlay, drawbox kombinasyonuyla filtre grafiği oluşturur
  • Daha fazla örnek Usage dokümanında görülebilir
  • Interactive Playground, typed-ffmpeg’i tarayıcıda doğrudan deneyebileceğiniz bir ortam sağlar
    • FFmpeg filtreleri ve komutlarıyla denemeler
    • Filtre grafiğini gerçek zamanlı görselleştirme
    • Girdi/çıktı yapılandırmasını test etme
    • Etkileşimli örneklerle öğrenme
    • Filtre grafiği paylaşma
  • Playground, yerel ortam kurulumu olmadan FFmpeg filtre zincirlerini öğrenmek ve prototiplemek için uygundur

Geliştirme yaklaşımı ve arka plan

  • İlk fikir, GPT-3 ile FFmpeg dokümantasyonundan doğrudan FFmpeg filtre SDK’sı üretmekti
  • Geliştirme sürecinde işi yalnızca GPT-3 ile tamamen otomatikleştirmenin sınırları olduğu görüldü ve SDK’yı tamamlamak için geleneksel kod üretimi yaklaşımına geçildi
  • GitHub Copilot ve GPT-3, geliştirme hızını artırmaya ve zaman kazandırmaya yardımcı oldu
  • ffmpeg-python projesinin API stili ve tasarım fikirleri typed-ffmpeg geliştirmesini etkiledi
  • Geliştirme bağımlılıkları pyproject.toml ve uv.lock ile yönetilir; geliştirme ortamı şu komutla kurulur
uv pip install --group dev

İlgili okumalar

1 yorum

 
GN⁺ 2025-05-31
Hacker News yorumları

  • Tüm komut satırı seçenek ayrıştırıcıları/araçları aslında kendi başlarına eksiksiz birer yapılandırma dili; tek tek araçları da o dilde yazılmış “program/yapılandırma” olarak görmek gerekir, ama bu nokta hafife alınıyor
    Unix kabuğu, nihai argv yorumlamasından önce sözcük ayırma yaptığı için sayısız lehçe dışarıdan benzer görünüyor; oysa gerçekte baş döndürecek kadar çeşitliler
    Eskiden /usr/bin içindeki tüm programlarda --help ve -h çalıştırmayı denemiştim; işe yarar yardım metni alamadığım oran epey yüksekti
    Bu yüzden ffmpeg gibi karmaşık bir araca tip eklemek hem pratik fayda sağlıyor hem de bu gerçeği daha iyi görünür kılmaya yardımcı oluyor

    • Asıl amaç bu olmayabilir ama foo --help veya foo -h yerine man foo komutunun daha güvenilir ve yararlı olduğunu düşünüyorum
    • Yeni başlayan biri olarak, çakışmanın nerede olduğunu merak ediyorum

  • İlginç ve aktif geliştiriliyor olması güzel, ancak ffmpeg-python ile benzer bazı sorunları var gibi görünüyor
    "color" gibi girdisi olmayan bir filtre belirtmenin yolu yok gibi; ayrıca Windows GUI uygulamalarında CMD penceresinin açılmasını engellemek için subprocess.CREATE_NO_WINDOW gibi bir bayrağı Popen’a geçirmenin yolu da görünmüyor
    ffmpeg için ffmpeg.compile() sonrasında doğrudan çalıştırmak mümkün, ama ffmpeg.probe() kullanan ffprobe tarafında bunu yapmak zor
    Düzenleme: Kaynak filtreyi ffmpeg.sources.color ile çözdüm. Genel filtrelerde vfilter/afilter kullanır gibi rastgele bir kaynak filtre kullanmanın bir yolu olup olmadığını merak ediyorum

  • Python’da betik tabanlı video işleme yapacaksanız, doğrudan Vapoursynth’e geçmenizi kuvvetle öneririm
    Baştan bu amaç için tasarlandı, aktif olarak bakımı yapılıyor, topluluğu ve araçları da iyi; ayrıca ffmpeg komut satırı arayüzüne bağlı değil
    https://www.vapoursynth.com/

  • typed-ffmpeg, “tam tip güvenliği, otomatik tamamlama, doğrulama”yı ana vaadi olarak sunuyor; peki burada genişlik ve yükseklik ya da x/y koordinatlarını string olarak vermek neden makul, açıklayabilir misiniz?

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

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

    • Sanırım bu değerler tamsayı değil, tamsayıya değerlendirilen ffmpeg ifadeleri olduğu için
      Örneğin ffmpeg belgelerinde şöyle bir örnek var: 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
      Bunu düzgün şekilde tip denetiminden geçirmek için bir tür DSL gerekecek gibi

  • İyi fikir. Kişisel olarak TypeScript sürümünü bekliyorum

    • Jules önizlemesine yaptırmayı denedim; uygulama oldukça safçaydı
      Aklıma gelen daha okunabilir yaklaşımlar var, ama çok kısa bir prompt ile üretildiğini düşünürsek hiç de kötü değil
      Merak ederseniz değişiklikler şu branch’te: https://github.com/matt-hensley/typed-ffmpeg/tree/feature/mu...
    • TypeScript’ten hiçbir yerde bahsedilmiyor

  • Birden çok dile üretim yapılabilmesi için ffmpeg komut satırını makine tarafından okunabilir bir biçimde tanımlayan bir kaynağa ihtiyaç var gibi

  • Görsel araç özellikle harika görünüyor. FFMPEG’in sunduğu parçaların hepsini bilmek zor olduğundan, modüler/görsel programlamanın gerçekten yardımcı olabileceği bir örnek gibi duruyor
    Küçük bir UX notu olarak, Win11/Chrome’da DEL tuşuyla düğüm veya kenar silebileceğimi sanmıştım
    Genel olarak güzel

    • Sonunda MS’in DirectShow GraphEdit’ine benzeyen bir şey çıkmış oldu

  • Güzel, ama tüm komutlar arasında frame pipe bağlantısını destekleyip desteklemediğini merak ediyorum
    Bana göre FFMpeg akışlarında en ilginç biçimler tam da o noktadan itibaren ortaya çıkmaya başlıyor

  • Güzel. Videoyu görsel olarak düzenlemek istiyorsanız, benim yaptığım aracı da deneyebilirsiniz: https://newbeelearn.com/tools/videoeditor/
    ffmpeg komutları üretiyor