我剛發布Cuekiyo v1.0.0，是一個開源本地網頁應用程式，用於建立動漫開頭和結尾合集影片.

這個想法很簡單：

選擇動漫標題 → 同意OP/ED歌曲 → 审核YouTube影片候選者 → 導出完成的MP4.

沒有雲端編輯器。沒有上傳步驟。沒有付費API依賴。整個系統在您的電腦上運行。

GitHub: https://github.com/unloopedmido/cuekiyo

我建立這個是因為製作動畫開頭/結尾合集的手動流程實在是痛苦。你會一堆瀏覽器分頁、複製的時間戳、分開的下載指令、剪輯工具、命名混亂、隨機資料夾，以及每當一個片段變更時重複的重新渲染。

Cuekiyo 將其轉換為一個引導式本地管線。它自動化那些煩瑣的部分，但在人類應該做出決定的時刻仍然會暫停。

問題

製作編輯影片聽起來簡單，直到你實際嘗試乾淨地完成它。

一個典型的手動工作流程看起來有點像這樣：

1. 選擇你想包含的動漫。
2. 找出開頭和結尾主題曲的名稱.
3. 為每首歌曲在YouTube上搜索.
4. 檢查哪些上傳可用.
5. 將鏈接或時間戳複製到某處.
6. 下載源視頻.
7. 剪輯每個片段.
8. 標準化或至少避免音頻劇烈不一致.
9. 添加標題疊加/字幕條。
10. 把所有東西串起來.
11. 當出現問題時重新渲染.

一次不難。問題在於重複。

如果你只剪一個影片，一個普通的影片編輯器就夠了。如果你在製作一個結構化的合集，包含很多動漫標題、多首主題曲、多個來源、一致的疊加效果和可預測的輸出資料夾，那個工作流程就變得更像一個小型媒體管道，而不是一次性的編輯。

那正是我實際想要解決的問題。

不是「取代影片編輯器」。

更像是：

給我一個處理重複性流程工作的本地工作室，同時仍然讓我能控制創意選擇.

Cuekiyo 做什麼

Cuekiyo 是圍繞著一個引導專案流程建立的.

你創建一個專案，選擇動漫標題，選擇你是否想要開場、結尾，或兩者都要，然後通過一組批准步驟.

核心流程是：

1. 建立專案
   命名它，選擇動漫標題，挑選歌曲類型，並設定覆蓋/渲染預設值

2. 選擇歌曲
   Cuekiyo載入主題數據並讓你批准哪些OP/ED曲目應包含在內

3. 審閱片段候選者
   該應用程式會來源 YouTube 候選，但您仍然選擇實際使用的內容。當自動化出錯時，您也可以貼上自己的連結。

4. 修剪並處理片段
   Cuekiyo 會在本地下載、探查、標準化、剪輯和疊加片段。

5. 確認渲染順序
   您在渲染前選擇最終順序。

6. 導出 MP4
   最終編譯已寫入您的本地專案資料夾.

重要的設計原則是這樣:

自動化應處理勞力，而非品味.

因此 Cuekiyo 在使用者門檻處暫停。選擇正確的歌曲、來源片段、修剪點和最終順序是主觀的。流程可以幫助，但它不應該假裝比您更了解您的品味.

為何採用本地優先？

我希望Cuekiyo能像一個桌面創意工具，但同時擁有網應用程式的開發速度和UI靈活性.

所以，我沒有建立一個托管的SaaS產品，Cuekiyo在本地運行：

• 後端在您的電腦上運行.
• 前端在您的瀏覽器中運行.
• 專案狀態存放在SQLite中.
• 媒體文件存放在data/projects/{id}/下.
• 渲染透過本地 FFmpeg 進行.
• 不需要上傳到隨機的雲服務.

這對於這種應用程式很重要，因為影片檔案很大，版權媒體有法律/服務條款複雜性，而且創作者通常希望直接控制他們自己的檔案。

本地優先也使專案運作更簡單。沒有用戶賬戶系統，沒有儲存計費，沒有托管的渲染隊列，沒有雲端工作隊伍，也沒有需要維護的數據庫伺服器.

這個代價是使用者需要安裝本地依賴：Python、Node.js、FFmpeg、FFprobe 和 yt-dlp。對於 v1，我接受了這個代價，因為我想先發布核心產品。

長期來看，我希望安裝體驗能夠更接近「下載、打開、建立」的模式

技術堆疊

Cuekiyo 分為 FastAPI 後端和 React 前端

主要技術堆疊是：

• 後端： FastAPI, SQLAlchemy, SQLite
• 前端： React 19, Vite, Tailwind CSS, shadcn/ui, React Router
• 媒體: FFmpeg, FFprobe, yt-dlp
• 疊加渲染: 基於Satori的HTML-to-PNG疊加
• 元數據: Jikan和AniList
• 進度更新: WebSockets
• 專案儲存: 本地SQLite資料庫 + 本地檔案系統

前端處理導向式工作流程和審核畫面。後端擁有管線、狀態過渡、媒體處理和文件系統安全性。

架構

在較高層次上，Cuekiyo 是一個包圍在媒體管線外的狀態機。

管線會經過階段，例如：

DRAFT
→ LOAD_THEMES
→ SONG_SELECTION
→ SOURCING
→ AWAITING_CANDIDATES
→ DOWNLOADING
→ PROBING_NORMALIZING
→ CUTTING
→ OVERLAYING
→ AWAITING_RENDER_ORDER
→ RENDERING
→ COMPLETED

有些階段會自動執行。其他的則是使用者門檻。

使用者門檻是重要的部分：

• 歌曲選擇
• 候選人審查
• 選擇性修剪/審查決策
• 最終渲染順序

其他一切都可自動化。

單一FastAPI進程擁有此流程管線。工作在背景執行緒中執行，進度透過WebSockets推送到前端。SQLite用於儲存專案狀態、工作狀態，以及用於主動流程管線鎖的心跳信號。

對於v1版本，Cuekiyo使用一個全域流程管線鎖。這意味著一次只有一個專案進行渲染/處理。這是故意保持簡單的。它避免了許多混亂的跨專案並發程式錯誤，同時使崩潰恢復過程保持可理解。

這是永久的最終架構嗎？不.

但對於一個 v1 本地應用程式，它是誠實且可維護的.

媒體管線

Cuekiyo 最困難的部分不是做出一個漂亮的 UI.

最困難的部分是做出一個媒體管線，它在真實世界的怪異情況下不會立即崩潰.

外部媒體工具很強大，但它們在很多方面都會失敗：

• 來源影片消失.
• yt-dlp 回傳非預期的元數據.
• FFmpeg 因編碼問題失敗.
• 片段有奇怪的時長或串流數據.
• 路徑包含你忘記處理的字元.
• GPU 編碼在你的電腦上正常，但在別人的電腦上不正常.
• 下載的檔案存在，但後續處理的產物不存在.

Cuekiyo 試圖將這些問題變得可管理，方法是將每個階段視為獨立的管線步驟.

下載、探測、正規化、切割、疊加和渲染是不同的操作。這讓流程更容易檢查、更容易重試，也更容易在 UI 中解釋。

我還特別注意將子進程參數作為參數陣列傳遞，而不是 shell 字串。對於一個操作用戶提供的鏈接和文件系統路徑的本地媒體工具來說，這不是可選的修飾。這是基礎的安全保障。

GPU 編碼和備用方案

我一開始就想要的一個功能是對 NVIDIA NVENC 的支援。

很多從事本地視頻工作的人擁有NVIDIA GPU，硬體編碼可以使渲染速度大幅提升。但硬性要求NVENC會是一個壞主意，因為不是每台電腦都支援它，而且FFmpeg的構建版本各不相同.

所以Cuekiyo會檢測NVENC支援，並在需要時回退到使用libx264進行CPU編碼。

那種備用方案很重要，因為本機優先軟體必須和諧地處理不同的用戶電腦。你不能假設環境跟你一樣。

前端

前端是使用 React 19、Vite、Tailwind CSS、shadcn/ui 和 React Router 建立的。

UI 的目標不是看起來像一個原始的管理面板。我希望它感覺更像一個創意工具：

• 專案卡
• 引導步驟
• 清晰的狀態狀態
• 剪貼候選者審查
• 可見的進度
• 影響流程的設置而不感覺可怕

前端透過 API 路徑和 WebSocket 進度事件與後端溝通。這個即時進度回饋很重要，因為媒體處理工作可能需要時間。如果 UI 無聲地靜置著，而 FFmpeg 正在運行，用戶就會認為出現了問題。

即使後端正在進行繁重的工作，前端也應該讓流程感覺上是可理解的。

最大的設計決策：只有在用戶需要做出選擇時才暫停

很多自動化工具會犯兩種錯誤：

1. 它們自動化太少，所以使用者還是要做所有煩人的工作。
2. 它們自動化太多，所以使用者必須在之後清理錯誤的決策。

Cuekiyo 的中間點是使用者門檻模型。

應用程式不應該在每個微小的技術步驟之後要求確認。那會很麻煩。

但它也不應該無聲地選擇每個 YouTube 来源和每個最終指令而不進行審查。那將是危險的.

所以流程自動通過機械階段，並在基於品味的決策處暫停.

那個模型最終讓產品感覺好得多。它還讓後端更容易理解，因為閘門狀態變成了狀態機的明確部分，而不是隨機的 UI 條件。

已知 v1 的妥協

Cuekiyo v1.0.0 不完美，我不希望假裝它完美.

v1 的最大妥協是：

一次只有一個管線工作

全域鎖讓工作執行者保持簡單，並防止多個專案爭奪本地資源。缺點是，目前還不支援跨專案並行。

對於本地v1發布，我認為這是可以接受的。並行任務在路線圖上.

簡化的concat/crossfade圖

當前渲染路徑支援編譯流程，但FFmpeg濾鏡圖可以更複雜。更豐富的渲染圖將使未來的過渡和多片段佈局更簡單.

重試可以更聰明

目前的重試流程對v1模型已經足夠好了，但一個更耐用的每階段游標會更好。那樣可以讓應用程式從確切的失敗邊界恢復，而不是推斷它。

這些不是隱藏的問題。它們被記錄下來，因為我更願意對架構保持誠實，而不是假裝每個v1的決定都是最終的。

我學到了什麼

Cuekiyo 教會了我一些事情.

1. 本地優先應用程式仍然需要產品思考

輕易會認為「本地工具」就是「開發者工具」。但 Cuekiyo 不僅僅是一個帶有 UI 的腳本。它需要入門指引、清晰的狀態、有用的錯誤信息，以及對非作者來說有意义的操作流程.

它本地的運行並沒有消除對產品設計的需求。

2. 對於工作流程繁重的應用程式，狀態機是值得的

當一個應用程式有長時間執行的任務、使用者門檻、重試、失敗、取消和進度事件時，隱含的狀態很快會變得痛苦。

讓管線狀態變得明確幫助很大。

3. FFmpeg 功能強大，但包裝程式碼很重要

FFmpeg 可以做到幾乎任何事情，但使用者不應該需要關心命令圖。真正的工作是圍繞它建立一個安全、可檢查的層次.

4. 「自動化所有事情」並非總是正確的產品

Cuekiyo 的最佳版本不是盲目創建影片的機器人。它是一個工作室，在移除重複勞動的同時，仍保持人類的選擇。

那個區別改變了我設計整個應用程式的方式.

下一步是什麼

既然 v1.0.0 已經公開，接下來的重點是讓 Cuekiyo 更容易嘗試.

最重大的優先事項是：

• 更好的首次運行體驗
• 一個可攜帶的桌面風格版本
• 更好的安裝/依賴性檢查
• 更聰明的重試行為
• 平行專案工作
• 豐富的渲染/交叉溶解選項
• 更多針對創作者的事務文件和示範

核心流程運作正常，但對於開源專案來說，可發現性和安裝摩擦非常重要。如果有人感興趣，他們應該能夠快速理解並嘗試專案

結論

Cuekiyo 開始只是一個利基想法，但它成為我到目前為止所建立的最完整的專案之一。

它整合了全栈應用程式開發、本地優先架構、媒體處理、背景工作、WebSocket 進度、UI/UX 設計和發布工程學到一個專案中。

這正是我想要加入作品集的類型：不僅僅是個示範，而是一個具備產品決策、權衡之處和實際工作流程的工具。

如果你對本地優先工具、媒體自動化、React/FastAPI 應用程式，或只是奇怪地特定的開源軟體感興趣，隨時可以查看。

GitHub: https://github.com/unloopedmido/cuekiyo

感謝您的星和回饋。