ChromaStage
คู่มือการใช้งานแบบละเอียด

Config ที่ใช้

{
  "image_preset": "square",       // → 1080×1080
  "image_format": "png",          // lossless
  "rename_pattern": "img_{n:03d}" // img_000.png, img_001.png, img_002.png
}

ผลที่ได้

• ✅ 3 ภาพ PNG ขนาด 1080×1080 ตรงเป๊ะ
• ✅ ZIP 2.0MB, PDF 193KB
• ✅ Chroma key: พื้นเขียวถูกลบออกหมด ขอบคนสะอาด

Preset: square

IMAGE_PRESETS = {
  "square":    (1080, 1080),  # IG square post
  "portrait":  (1080, 1350),  # IG portrait post
  "story":     (1080, 1920),  # IG/TikTok story 9:16
  "fb_cover":  (820, 312),    # FB cover banner
  "youtube":   (1280, 720),   # YouTube thumbnail
  "wallpaper": (1920, 1080),  # 1080p wallpaper
  "custom":    None,          # use output_w / output_h
}

Config

{
  "image_preset": "portrait",      // → 1080×1350
  "image_format": "jpg",           // lossy
  "jpg_quality": 80,               // 0-100
  "watermark": {
    "enabled": true,
    "text": "© ChromaStage 2026",
    "position": "bottom-right",
    "opacity": 0.7,
    "size": 36,
    "color": "#FFFFFF"
  }
}

ผล

• ✅ ขนาด 1080×1350 ตรงเป๊ะ
• ✅ JPG quality 80 → ไฟล์เล็ก เหมาะกับ social upload
• ✅ Watermark render ที่มุมขวาล่าง

Config

{
  "image_preset": "story",          // → 1080×1920 (IG/TikTok 9:16)
  "image_format": "webp",           // เล็กกว่า PNG เยอะ คุณภาพดีกว่า JPG
  "rename_pattern": "story_{n:04d}", // story_0000.webp, story_0001.webp, ...
  "watermark": {
    "enabled": true,
    "text": "ทดสอบ 🎉 ภาษาไทย",    // Thai + emoji
    "position": "center",
    "opacity": 0.8,
    "size": 60,
    "color": "#FFEB3B"               // สีเหลือง
  }
}

🐛 Regression Note

ก่อนแก้ bug B3: การ save config ที่มี Thai text ใน watermark จะได้ 500 UnicodeEncodeError: 'charmap' codec can't encode characters บน Windows (cp1252 default)

Fix: เพิ่ม encoding="utf-8" ใน app/storage.py:write_meta()

ผล

• ✅ Thai + emoji ไม่ crash — render 3.66s
• ✅ 1080×1920 ตรงเป๊ะ
• ✅ ไฟล์ story_0000.webp, story_0001.webp, ...

Config

{
  "image_preset": "fb_cover",       // → 820×312
  "image_format": "jpg",
  "jpg_quality": 70,
  "rename_pattern": "cover_{n}"
}

ผล

• ✅ 0.51s render — เร็วมากเพราะ output เล็ก
• ✅ Aspect ratio 820:312 ≈ 2.63:1 (banner)

Config

{
  "image_preset": "youtube",        // → 1280×720
  "image_format": "png",
  "rename_pattern": "yt_{n}"
}

Tip

YouTube แนะนำ thumbnail อย่างน้อย 1280×720 ขนาดใหญ่สุด 2MB. PNG ที่ preset นี้จะใหญ่กว่า JPG แต่คมชัดกว่าสำหรับข้อความ

Config

{
  "image_preset": "wallpaper",      // → 1920×1080
  "image_format": "jpg",
  "jpg_quality": 92,
  "watermark": {
    "enabled": true, "text": "Desktop Wallpaper",
    "position": "bottom-left", "opacity": 0.5, "size": 28
  }
}

เรียกดู

curl -b jar.txt -o cut.png http://127.0.0.1:30089/api/jobs/<JOB>/person_cut

วิเคราะห์ผล

mode: RGBA (4 channels)
size: 1500×1000
transparent pixels (alpha<50): 1,058,893 / 1,500,000 = 70.6%
opaque pixels     (alpha>200):   438,138 / 1,500,000 = 29.2%

การใช้งาน

• ✅ ตรวจสอบคุณภาพ chroma key — ถ้า % transparent ต่ำเกินไป = key ไม่สะอาด
• ✅ นำไปใส่ program อื่น (Photoshop, GIMP) เพื่อ edit เพิ่ม
• ✅ ใช้เป็น asset ตั้งต้นสำหรับ render pipeline อื่น

Config

{
  "scene_duration": 5,         // แต่ละ scene 5 วินาที
  "transition": "cut",         // เปลี่ยนฉากแบบตัดตรงๆ (เร็วสุด)
  "transition_duration": 0.5,  // ไม่ใช้กับ cut แต่เก็บไว้
  "ken_burns": false,          // ไม่มี zoom
  "output_w": 1280,
  "output_h": 720,
  "fps": 30
}

ผลที่ได้

• ✅ MP4 ขนาด 1280×720, 30fps
• ✅ duration = 15.000000s exact (ffprobe confirmed)
• ✅ File size 1.15MB (เล็กมาก เพราะ cut transition ไม่มี motion)
• ✅ Render time 1.83s = 8x realtime

Pipeline

person photo → cut_person (chroma+despill) → RGBA PNG
  ↓
for each background:
  composite_scene (overlay centered) → still PNG
  render_scene_clip (Ken Burns optional) → scene_NNN.mp4
  ↓
concat with xfade (or cut) → merged.mp4
  ↓
apply text overlay (drawtext) → overlay.mp4
  ↓
apply BGM (stream_loop + volume) → final.mp4

Config

{
  "scene_duration": 8,
  "transition": "fade",          // จางเข้า-ออก ระหว่าง scene
  "transition_duration": 0.8     // ใช้ 0.8s สำหรับ fade
}

💡 Fade ใช้ ffmpeg xfade filter — ต้องมี scene ≥ 2 จึงจะเห็น effect

Config

{"scene_duration": 3, "transition": "slide-zoom", "transition_duration": 0.5}

TRANSITIONS ที่รองรับ: cut · fade · slide-zoom

Steps

# 1) สร้าง BGM test (10s sine wave)
python -c "
import wave, struct, math
sr = 22050
with wave.open('test.wav','wb') as w:
    w.setnchannels(1); w.setsampwidth(2); w.setframerate(sr)
    for i in range(sr*10):
        s = int(8000 * math.sin(2*math.pi*440*i/sr))
        w.writeframes(struct.pack('<h', s))"

# 2) Upload BGM
curl -b jar.txt -F "file=@test.wav" \
  http://127.0.0.1:30089/api/jobs/<JOB>/bgm

# 3) Config + Render
{
  "scene_duration": 5,
  "bgm_volume": 0.5          // 0.0 - 1.0
}

รองรับ audio formats

ALLOWED_AUDIO_EXTS = {".mp3", ".wav", ".m4a", ".aac", ".ogg", ".flac"}
MAX_AUDIO_BYTES = 50 * 1024 * 1024  // 50MB

Behavior พิเศษ

• ✅ BGM สั้นกว่า video → stream_loop -1 loop จนจบ
• ✅ BGM ยาวกว่า video → ตัด audio ตาม video duration
• ✅ ไม่มี BGM → MP4 ไม่มี audio stream (ยัง render ได้)

Config

{
  "scene_duration": 4,
  "transition": "cut",
  "text_overlay": {
    "text": "Hello World",
    "position": "bottom-center",
    "color": "#FFFFFF",
    "size": 48,
    "opacity": 1.0
  }
}

Text Overlay fields

• text: ข้อความ ≤120 chars
• position: 9 ตำแหน่ง (เหมือน watermark)
• color: hex #RRGGBB หรือ #RRGGBBAA
• size: 10-200 (px)
• opacity: 0.0-1.0

Config

{
  "scene_duration": 4,
  "transition": "cut",
  "text_overlay": {
    "text": "สวัสดี 🎉 ไทยแลนด์",
    "position": "top-center",
    "color": "#FFD700",
    "size": 56,
    "opacity": 0.95
  }
}

Steps

# Upload intro
curl -b jar.txt -F "file=@intro.jpg" \
  http://127.0.0.1:30089/api/jobs/<JOB>/intro

# Upload outro
curl -b jar.txt -F "file=@outro.jpg" \
  http://127.0.0.1:30089/api/jobs/<JOB>/outro

# Config
{
  "scene_duration": 3,
  "intro_duration": 2.0,
  "outro_duration": 2.0
}

💡 Intro/outro ใช้ render_static_clip() — เปลี่ยนภาพนิ่งเป็น MP4 แบบ static

Config

{
  "scene_duration": 5,
  "ken_burns": true    // ← เปิด slow zoom
}

Effect

กล้องค่อยๆ zoom in จากขอบเข้าไปกลางภาพ ตลอด scene_duration — ทำให้ภาพนิ่งดู dynamic

💡 ใช้ /preview-clip/{n} ดู effect 3s ก่อน render เต็ม — เซฟเวลา debug

Config

{
  "scene_duration": 15,    // 4 × 15 = 60s (limit)
  "transition": "cut"
}

Limits

• scene_duration: 0.5 - 30 วินาที (validated)
• จำนวน backgrounds: สูงสุด 30
• Theoretical max video: 30 × 30 = 900 วินาที (15 นาที)

✅ ffprobe confirmed: duration=60.000000s exact

Config

{
  "scene_duration": 4,
  "transition": "fade",
  "transition_duration": 0.5
}
// 5 backgrounds uploaded

ก่อนแก้ (B10)

Source: 6000×4000 pixels, EXIF orientation=8 (90° CCW)
Upload → stored as-is
Render → person นอนตะแคง
→ ต้อง pre-rotate ก่อน upload (workaround)

หลังแก้

Source: 6000×4000 pixels, EXIF orientation=8
Upload → ImageOps.exif_transpose() applied
        → file re-saved as 4000×6000, EXIF stripped
Render → person upright ✓

ที่ใช้

from PIL import Image, ImageOps
from .storage import auto_orient_image

# Called automatically after every person/bg/intro/outro upload:
auto_orient_image(save_path)