Darija 影片剪輯套件（darija-video-editing）

專為高碼率手機攝影機拍攝的摩洛哥達里賈語（الدارجة المغربية） 影片而設計的完整管線，並在 Storyteller FilmCraft 中進行剪輯。

解決達里賈語手機影片製作的四個關鍵障礙：

MTP 匯流排停滯與斷線：具彈性序號檔案拉取，支援區塊級位元組附加續傳。
機器播放延遲與磁碟膨脹：超緊湊 960×720 幀內友好的剪輯代理（-bf 0、-tune fastdecode），解碼速度達 138+ fps，同時節省 >96% 磁碟空間。
FilmCraft 語言不匹配：以 faster-whisper（--language ar）取代預設的英文轉錄，並透過 stdin 安全串流傳入時間戳記，繞過 Linux ARG_MAX 限制。
YouTube 成長協同效應：先建構長片主線敘事，再從中衍生出高留存率的 9:16 垂直 Shorts，並透過 YouTube「相關影片」漏斗直接連結。

5 階段操作協議

[手機（MTP）] ──> 步驟 1: mtp_ingest.py ──> [原始影片]
                       │
                       ├──> 步驟 2: generate_proxies.py ──> [960x720 代理影片（約 1.5GB）]
                       │
                       ├──> 步驟 3: darija_transcribe.py ──> [逐字時間戳記]
                       │
                       └──> 步驟 4: filmcraft_pipeline.py ──> [LongForm_Fisik101.fcproj]
                                                                     │
                                                       （主剪輯審核通過）
                                                                     │
                                                       步驟 5: 9:16 Shorts 漏斗

階段 1：手機與 MTP 彈性匯入

手機攝影機影片（例如 MotionCam Pro 的 4K/UHD Open Gate）經由 USB 傳輸時會產生 40–100 GB 的檔案。標準的 GVFS/MTP GUI 複製在長時間傳輸過程中容易崩潰或凍結。

執行具彈性的序號匯入工具：

python3 scripts/mtp_ingest.py \
  --dst "/path/to/project/raw_footage" \
  --pattern "*.mov" \
  --date "YYMMDD"

智能區塊續傳：如果一個 10 GB 的檔案在中途中斷，引擎會讀取磁碟上現有的位元組數，直接跳至該偏移量，並附加剩餘的區塊，無需重新下載前面的 GB 級資料。
序號線程：強制執行單一檔案傳輸，避免 MTP 協議管道碰撞。

階段 2：輕量剪輯代理（磁碟與 CPU 友善）

原始 4000×3008 影片在一般 CPU 上無法以即時速度播放（約 18 fps）。這些代理影片能提供即時、零延遲的時間軸拖曳體驗，同時僅消耗不到原始磁碟空間的 4%：

python3 scripts/generate_proxies.py \
  --input "/path/to/project/raw_footage" \
  --output-dir "/path/to/project/proxies" \
  --width 960 \
  --crf 24

規格：
- 縮放：960×720（精確 4:3）或 960×540（16:9）。
- 零 B 幀（-bf 0）與 GOP 60：即時幀搜尋，無需預測性幀間解碼延遲。
- 快速解碼調校（-tune fastdecode）：停用高複雜度的 CABAC 與 loop 內去塊濾波器；在 FilmCraft 中解碼速度達 138+ fps。
- 音訊透通（-c:a copy）：逐位元無損複製原始 48 kHz 立體聲，保留 A1 音軌上清晰的波形與對話同步。
- 磁碟佔用：超過 1 小時的 4K 影片總計約 1.5 GB（節省 >96% 空間）。

階段 3：摩洛哥達里賈語語音辨識與原生 FilmCraft 注入

FilmCraft 原生的自動轉錄預設為英文（"defaultLanguage": "en"）。請使用達里賈語轉錄引擎來提取逐字時間戳記：

uv run --python 3.12 --with "faster-whisper" --with "av<14" python3 \
  scripts/darija_transcribe.py \
  --input "/path/to/clip.mov" \
  --output "/path/to/transcripts/clip.json" \
  --model small \
  --language ar

安全的 Stdin 轉錄注入（繞過 `ARG_MAX`）

長片段（>5 分鐘）會產生數千個帶時間戳記的單字。透過命令列字串傳遞會導致 OSError: [Errno 7] Argument list too long。

請務必使用 filmcraft-cli run - 將 JSON 命令負載透過 stdin 串流傳入：

import json, subprocess
TICKS_PER_SEC = 254016000000

cmd_obj = {
    "id": "transcript.set",
    "params": {
        "item": item_id,
        "transcript": {
            "language": "ar",
            "speakers": [{"name": "Speaker 1"}],
            "words": [
                {
                    "text": w["word"],
                    "start": int(round(w["start"] * TICKS_PER_SEC)),
                    "end": int(round(w["end"] * TICKS_PER_SEC)),
                    "speaker": 0
                }
                for w in words_data
            ]
        }
    }
}

subprocess.run(
    ["filmcraft-cli", "--project", "project.fcproj", "--save", "run", "-"],
    input=json.dumps(cmd_obj) + "\n",
    text=True
)

階段 4：長片時間軸主線組裝

透過單一命令套件協調整個 FilmCraft 專案與時間軸：

# 1. 初始化主 4K 序列（V1-V3, A1-A3）
python3 scripts/filmcraft_pipeline.py init \
  --project "/path/to/LongForm_Fisik101.fcproj" \
  --sequence-name "Master Assembly" \
  --width 3840 --height 2160 --fps 24.0

# 2. 批次匯入所有原始影片
python3 scripts/filmcraft_pipeline.py import \
  --project "/path/to/LongForm_Fisik101.fcproj" \
  --media "/path/to/raw_footage"

# 3. 按時間順序將片段組裝到 V1 / A1 軌道
python3 scripts/filmcraft_pipeline.py assemble \
  --project "/path/to/LongForm_Fisik101.fcproj"

# 4. 將產生的代理影片附加到所有項目
python3 scripts/filmcraft_pipeline.py attach-proxies \
  --project "/path/to/LongForm_Fisik101.fcproj" \
  --proxies-dir "/path/to/proxies"

# 5. 將達里賈語轉錄注入所有項目
python3 scripts/filmcraft_pipeline.py attach-transcripts \
  --project "/path/to/LongForm_Fisik101.fcproj" \
  --transcripts-dir "/path/to/transcripts"

全域偏好設定

確保 FilmCraft 在啟動時自動預設使用代理影片播放，請確認 ~/.local/share/filmcraft/preferences.json 中包含：

"enableProxies": true

階段 5：YouTube 成長與 Shorts 衍生漏斗（@fisik101）

長片主剪輯版本打磨並審核通過後：

策略性發布節奏：
- 長片：每週 1 到 2 部影片（兩次上傳之間間隔 48–72 小時，以便瀏覽與推薦演算法建立索引）。
- Shorts：每天 2 到 3 部 Shorts，每部間隔 3 到 4 小時（例如 GMT+1 時間 13:00、17:00、21:00）。
相關影片漏斗：
- 針對從長片主線中提取的每一部 Shorts，在 YouTube Studio 中將「相關影片」連結設定為該長片影片。
- 將 Shorts 的高流量直接轉化為長片觀看時間與頻道訂閱數。
短格式畫布與樣式：
- 9:16 垂直畫布（1080×1920）。
- 高對比動態字幕，位於麥克風/胸部安全區域（margin_v: ~420px）。
- 鉤子 $\rightarrow$ 故事 $\rightarrow$ 回報結構（去除超過 $0.4$ 秒的空白，並保留 80 毫秒的輔音保護緩衝區）。

darija-video-editing