stickman-explainer은(는) 무엇을 하나요?

Kısa bir metni bitmiş 1080×1920 mp4'e dönüştürür. Bir storyboard JSON'u yazarsınız; scripts/render.py her kareyi çizer (sallantılı mürekkep çizgileri, 8 fps'de line-boil, fade/wipe/pop açılımları) ve ffmpeg ile kodlar.

assets/example_storyboard.json yalnızca söz dizimi örneğidir (3 sahne); yerleşimini veya karakter aksesuarlarını şablon olarak kopyalamayın.

Görsel stil varsayılanları

9:16 tuval (1080×1920, 30 fps) kullanın. Her sahneyi tek bir fikirle sınırlayın, genellikle 2.5–4 saniye; platform güvenli alanlarının içinde kısa altyazılar kullanın.
Sıcak kağıt (#f3ebdd), koyu mürekkep (#2b2723) ve anlamsal tuğla kırmızısı vurgu (#b8372d) kullanın. Güneş altını (#d89d48) yalnızca güneş motifi için isteğe bağlıdır. Geri kalanı düz bırakın: degrade, gölge veya 3D efekti yok.
Net yüzlere ve bol negatif alana sahip basit siyah mürekkep figürler çizin. Hikaye veya kullanıcı istemedikçe miğfer, taç, pelerin, kırmızı giysi veya başka aksesuar eklemeyin. Tarihi bir isimden kostüm çıkarmayın.
Sahneleri okunabilir tutun: en fazla 2 karakter ve 5 küçük simge. Ana konuyu baskın yapın; altyazıların ve ögelerin üst üste binmesinden kaçının. En fazla 2 altyazı satırı kullanın.
Karmaşık aksesuarları tanınabilir yapın. Belirgin çapraz ilmekler, sıkı bir merkez ve görünür ip uçlarıyla bir düğüm çizin. Kılıca net bir kabza, el koruması ve sivri bir namlu verin. Kesme anından sonra iki ip ucu arasında görünür bir boşluk bırakın.
Anlatım zamanlamaları mevcut olduğunda, kırmızı altyazı vurgusunu anlatım boyunca o anda konuşulan kelimeyi takip edecek şekilde yapın. Boşlukla ayrılmış her altyazı kelimesi için bir karaoke aralığı kullanın; aktif olmayan kelimeler normal metin renginde kalır.
Asimetrik yerleşimleri tercih edin ve kasıtlı negatif alan bırakın. Zemin çizgileri, güneş, başlık kartları, düşünce balonları ve diğer motifler isteğe bağlıdır; yalnızca sahneyi desteklediklerinde seçin.

İş akışı

Metin → sahneler. Hikayeyi tek cümlelik sahnelere bölün (≤ 6 altyazı kelimesi, her biri 2.5–4 sn). Desen: başlık kartı → düğüm/çatışma → somut açıklama. Her sahne tam olarak bir yeni bilgi ekler. Anlatım sağlandığında, sahne sınırlarını konuşulan cümlelere göre hizalayın.
Her cümle için bir görsel seçin. Sahne başına bir metafor: karakter + aksesuar, düşünce balonu veya bir simge sırası (X = "sahip değil"). ≤ 2 karakter ve ≤ 5 simge tutun.
Storyboard'u yazın (aşağıdaki şema). Kelime düzeyinde anlatım zamanlamalarıyla birlikte, boşlukla ayrılmış her altyazı kelimesi için kırmızı vurgunun konuşulan kelimeyi takip etmesi amacıyla bir karaoke aralığı ekleyin. **word** kullanımını yalnızca kelime zamanlaması olmadığında statik vurgu için kullanın; statik işaretlemeyi karaoke ile birleştirmeyin.
Önce kareleri kontrol edin (hızlı, ~2 sn/sahne): python scripts/render.py story.json --stills out/stills → her scene_NN.png'yi açın, çakışma/yerleşimi düzeltin, tekrarlayın.
Taslak video: python scripts/render.py story.json out/draft.mp4 --draft (süper örnekleme yok, 12 fps).
Final: python scripts/render.py story.json out/final.mp4 [--audio voiceover.mp3]. Sahne süreleri seslendirme cümle uzunluklarıyla eşleşmelidir; ffprobe ile sesi ölçün ve duration'u buna göre ayarlayın. Kelime aralıkları, sahnenin başlangıcından itibaren saniye cinsindendir ve anlatım hizalamasından veya dikkatli dinlemeden gelmelidir. Her kırmızı kelimenin konuşulan sesiyle birlikte, öncesinde veya sonrasında değil, doğru zamanda göründüğünü kontrol edin.

Hata mesajları ve doğrulama

render.py storyboard'u çizmeden önce doğrular: bilinmeyen type/pose/face/kind/font, eksik zorunlu alan, aynı sahnede tekrarlanan id, duration <= 0, tek noktalı lines yolu, tek sayılı (çift olmayan) çözünürlük ve olmayan carry id'si traceback yerine açık mesajla reddedilir. Hiçbir zaman görünmeyecek ögeler (sahne bitişinden sonraki at) için uyarı verilir. Ses dosyası videodan kısaysa sonu sessizlikle doldurulur, uzunsa kesilir; video süresi asla değişmez.

Storyboard şeması

{"meta": {"width":1080,"height":1920,"fps":30,"boil_fps":8,"transition":0.18,
          "palette":{"accent":"#b8372d"}, "audio":null, "font_dirs":[]},
 "scenes":[{"duration":3.4, "caption":"Büyük **İskender**'di.",
            "caption_at":0.5, "caption_y":null, "elements":[ ... ]}]}

Konuşmayı takip eden kelime vurgusu için, caption'daki boşlukla ayrılmış her kelime başına birer { "start": saniye, "end": saniye } nesnesi içeren bir karaoke dizisi sağlayın. Zamanlar sahneye göre yereldir; kırmızı vurgu her aralıkta geçiş yapar. karaoke mevcut olduğunda caption **...** işaretlemesi içermemelidir.

{"duration":2.8, "caption":"Düğümü tek hamlede kesti.", "caption_at":0.35,
 "karaoke":[{"start":0.35,"end":0.76},{"start":0.76,"end":1.02},
            {"start":1.02,"end":1.53},{"start":1.53,"end":2.15}],
 "elements":[ ... ]}

Her öge: type, isteğe bağlı id (taşıma için), at (s, görünme zamanı), dur (açılma süresi), anim = fade | wipe | rise | pop, until/out_dur (sönme süresi). x,x2,y,ground ≤ 2 olan konumlar genişlik/yüksekliğin kesri, aksi halde piksel olarak okunur. Boyutlar her zaman pikseldir.

type	anahtar alanlar
`ground`	`y` (zorunlu); `x`, `x2` isteğe bağlı, verilmezse tuvalin ~%2–%98'i — sallantılı taban çizgisi
`sun`	`x`,`y`,`r`,`rays`
`text`	`text` (`accent` işaretlemesi), `x`,`y`,`size`,`font` = sans/sans_bold/sans_light/serif, `tracking`, `caps`, `color`, `max_w`, `max_lines` (varsayılan 3), `rules` (başlık kartı için çift çizgi; genişliği ve aralığı metne göre otomatik)
`figure`	`x`,`ground`,`h`,`head_r`, `pose` = stand/arms_open/point/wave/think/shrug/sit, `dir` (±1), `face` = neutral/smile/sad/surprised/angry, isteğe bağlı `accessory` = helmet/crown/hat/glasses, isteğe bağlı `cape`, `look`
`prop`	`kind` = barrel/bowl/bucket/house/book/box/triangle/coins/tree, `x`,`y` (üst sol), `w`,`h`, `cross` (vurgu X), `flip`
`thought`	`x`,`y`,`w`,`h`, `tail_to` [px,py] (kafa pozisyonu), `inner`: balon-yerel px cinsinden öge listesi
`lines`	`paths` (nokta listelerinin listesi, yerel px), `closed`, `smooth`, `color`, `width` — herhangi bir özel şekil için kaçış kapağı

Sahneler arası süreklilik (carry)

Bir sahnenin ögesini sonraki sahneye taşımak için ögeye id verin, sonraki sahnede carry ile çağırın. Taşınan öge aynı çizgi titreşimiyle (aynı seed) başlar, yani sahne değişse bile "aynı çizim" olarak görünür; yeni sahne geçişi varsayılan olarak kesmedir (çapraz geçiş yok).

"carry": [
  "ground",
  {"id": "sun",  "set": {"r": 122}},
  {"id": "alex", "set": {"x": 120, "face": "smile"}, "tween": {"at": 0.1, "dur": 0.9}},
  {"id": "diog", "until": 0.1, "out_dur": 0.5}
]

Satırlar sırayla: "ground" aynen taşınır · sun alan değiştirilerek taşınır (değişiklik sahne başında anında olur) · alex hem alan değiştirir hem konumu süre boyunca kayar (tween) · diog taşınır ama sahne içinde sönerek çıkar.

"carry": "all" her şeyi taşır ("carry_except": ["id", ...] hariç tutar). Altyazı asla taşınmaz.
Taşınmayan öge sahne başında anında kaybolur; yumuşak kaybolması için until/out_dur kullanın. until ile sönen öge sonraki sahneye taşınamaz.
tween yalnızca konum (x ve y/ground) animasyonları; boyut (r, h, w) ve görünüm (face, pose) değişimleri sahne başında anında uygulanır.
Taşınan ögeler yeni ögelerin altında çizilir. Taşınacak ögeler için sahneler arası id benzersiz olmalıdır.
Aynı id'li öge her sahnede aynı seed'i kullanır; sahneye özgü yeni öge için id vermeyin.

render.py içindeki PROPS / hands sözlüklerini genişleterek yeni aksesuarlar/pozlar ekleyin; aynı mürekkep stilini koruyun (stroke() kullanın, asla düz çizgiler kullanmayın).

Yerleşim: her video için yeniden karar verin

Sabit koordinat/şablon yok. Her videonun konusu farklı olduğu için yerleşimi sahnenin içeriğinden türetin:

Önce o cümlenin tek görsel fikrini seçin (karşılaştırma, liste, hayal, yolculuk, sayı…), sonra ona uyan düzeni kurun. Aynı videoda sahneler arasında düzen değişebilir.
Önemli olan ögeye yer açın: ana özne en büyük/en belirgin olsun; yan ögeler küçük kalsın. Boş alan (negatif alan) bilinçli bırakılsın.
Büyüklük, konum ve sayı içeriğe göre değişir (1 karakter mi, 2 mi; simge şeridi mi, tek büyük nesne mi, harita/zaman çizgisi mi). Gerekirse lines ile özel şekil çizin.
Tarihi kişilere otomatik kostüm/başlık eklemeyin. Figürler varsayılan olarak aksesuarsız çizilir; miğfer, taç, şapka veya pelerin yalnızca anlatı ya da kullanıcı açıkça gerektiriyorsa eklenir. Vurgu rengini karakterin kıyafetine dekor olarak yaymayın.
Düğüm ve kesme sahnelerinde nesneyi okunaklı kurun: ipi belirgin biçimde üst üste geçen birkaç ilmekle çizin, merkezde sıkı düğüm gösterin ve ip uçlarını ayırt edin. Kılıçta kabza, el koruması ve sivri namlu seçilebilsin. Kesme anından sonra iki kesik ip ucunu aralıklı ve açıkça görünür bırakın; kılıç ve düğüm altyazı tarafından kapatılmasın. Özel ip/kılıç şekillerini lines ile çizin.
Zemin çizgisi, güneş, başlık kartı gibi motifler isteğe bağlıdır; konuya uymuyorsa kullanmayın (ör. iç mekân, gece, soyut kavram).
Altyazıyı okunur ve platform arayüzünden uzak bir yere koyun; çakışırsa caption_y ile oynatın. Çakışma ve taşmayı karelerde gözle kontrol edin, sayıya güvenmeyin.
Çizim koordinatları 1080×1920 tuvalde piksel (veya 0–2 arası oran) olarak verilir; değerleri her sahne için sıfırdan planlayın.

Dikkat edilmesi gerekenler

Kodlamadan önce her zaman kareleri görüntüleyin; üst üste binen ögeler ve kırpılmış güneş ışınları yaygın kusurlardır. Taslak için --draft, ayrıntılı için tam render kullanın: değişmeyen kareler yeniden çizilmez, 10 sn'lik video tam kalitede yaklaşık 20 sn sürer.
Altyazı %86 genişliğe kadar satır kaydırır (en fazla 3 satır), ancak bir kelime sığmazsa ya da 3 satırı aşarsa küçülür. 2 satırı geçen cümleyi iki sahneye bölün. Varsayılan altyazı konumu yalnızca yedektir; gerekirse sahnede caption_y verin.
Fontlar: Poppins ve Playfair Display (veya Lora) kurun ya da --font-dir verin. Hiç TrueType font bulunamazsa renderer uyarı basar ve Türkçe karakterler (İ ş ğ â) eksik çıkabilir; karelerde kontrol edin. Linux, macOS ve Windows font klasörleri taranır.
Vurgu rengini anlamsal tutun (özne, anahtar kelime, olumsuzluk). Daha fazla renk eklemeyin.
karaoke mevcut olduğunda, kırmızı altyazı vurgusu, sağlanan aralıkları kullanarak anlatımı kelime kelime takip eder. Ekranda sabit kırmızı bir anahtar kelime bırakmayın; aktif olmayan kelimeleri altyazı metin renginde işleyin.

stickman-explainer