StoryForge 🎙️✨

將文字故事轉換為具備情緒、角色演繹與生動聲音的有聲書電腦軟體。

StoryForge 就像一位住在你電腦裡的 AI 總導演。只要把心中的故事靈感或文字交給他，他就會從劇本編寫、角色設定、情緒指導到配樂聲音演繹一手包辦，為你錄製出一部生動好聽的完整廣播劇/有聲書 MP3！

不需要懂寫程式，不論你是用 Windows 還是 Mac，只要跟著以下三個簡單步驟，就能一鍵召喚 StoryForge 開始創作！

---

🚀 三分鐘快速上手

第一步：召喚小助手（安裝 uv 工具）

uv 就像是電腦裡的超級快遞員，能幫你免安裝、自動把軟體所有零件準備好。

• 🪟 Windows 使用者：

  1. 在鍵盤上同時按下 Win + X 鍵，點選 「終端機」 或 「PowerShell」。
  2. 複製以下指令貼進黑視窗中，並按 Enter 執行：

     powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
     

• 🍎 Mac 使用者：

  1. 在鍵盤上同時按下 Command + 空白鍵，輸入 Terminal 並打開 「終端機」。
  2. 複製以下指令貼進終端機中，並按 Enter 執行：

     curl -LsSf https://astral.sh/uv/install.sh | sh
     

第二步：一鍵啟動 StoryForge（免安裝！）

在剛剛打開的黑色終端機小視窗中，貼上以下這行指令並按 Enter：

uvx storyforge-studio

💡 小秘訣： 電腦會自動準備好所有環境與音訊小工具，只要幾秒鐘，美麗的 StoryForge 操作視窗 就會自動彈出來囉！ (若欲測試開發中未發布版本，亦可使用 uvx --from git+https://github.com/jonascheng/storyforge-studio storyforge)

---

第三步：領取並設定免費通關鑰匙（Gemini API 通行證）

首次啟動或尚未設定通行證時，畫面會自動跳出提醒視窗，指引您前往右上角的 「⚙️ 設定」 完成設定：

1. 點擊設定畫面中 Gemini API Key 欄位旁的超連結，前往 Google AI Studio 網頁並登入您的 Google 帳號。
2. 點擊畫面上的 「Get API key」，接著 「Create API key」，建立並複製那串英文數字密碼。
3. 回到 StoryForge 貼上密碼並點擊 「儲存」。（只要設定一次，下次打開不用再輸入！）

💡 進階設定：在「⚙️ 設定」視窗中，您也可以依需求自由調整 「思考深度 (Thinking Level)」（預設 MEDIUM）與 「場景間隔停頓 (秒)」（預設 1 秒）。

---

📖 製作第一本有聲書（操作指引）

當 StoryForge 視窗跳出來後，照著以下清晰步驟就能輕鬆完成作品：

 [1. 通行證設定] ⚙️
        ↓
 [2. 輸入故事想法] 💡（或 📂 載入舊劇本）
        ↓
 [3. 故事劇本確認與微調] 📝（角色卡片、世界觀、✨ 讓 AI 重寫 / ↩️ 復原）
        ↓
 [4. 廣播劇本拆解與錄音] 🎬（BGM 配樂、台詞情緒、🎙 生成語音 / ▶️ 試聽）
        ↓
 [5. 產出完整有聲書] 🔊

1. ⚙️ 確認通行證設定

• 確保已依照快速上手第三步，在右上角 「⚙️ 設定」 中填寫 Gemini API 通行證。
• （首次啟動未設定時，系統會自動跳出提醒視窗引導您。）

2. 💡 輸入故事想法（或載入舊進度）

• 在「1. 輸入故事想法」文字框中貼上您的故事點子或大綱（例如：一個關於會說話的貓和失憶魔法師的冒險故事...）。
• 點擊 「✍️ AI 撰寫劇本」，AI 編劇會自動生成故事標題、完整情節、角色設定與世界觀規則。
• (若是過去製作過的故事，可點擊 「📂 載入舊劇本」 從清單中點選，或點擊「📁 從電腦資料夾瀏覽...」直接開啟舊進度)。

3. 📝 故事劇本確認與微調

• 進入「2. 故事劇本確認」畫面，您可以檢視並自訂所有故事設定：
  • 故事內容：可直接修改內文，亦可點擊 「🔍 放大」 開啟全螢幕專注編輯。
  • 角色設定：檢視各角色卡片，包含角色名稱、聲音類型（例如：童趣活潑[男]）與個性背景；可點擊 「➕ 新增角色」 或刪除角色。
  • 世界觀規則：檢視故事的世界背景，同樣支援 「🔍 放大」 編輯。
• AI 靈感微調：想改變劇情走向？在下方輸入修改需求（例如：「讓結局更感人」、「加入一個反派角色」），點擊 「✨ 讓 AI 重寫」；若不滿意重寫結果，點擊 「↩️ 復原」 即可隨時回到上一版。
• 確認滿意後，點擊下方 「🎬 確認劇本，產生廣播劇」。

4. 🎬 廣播劇本拆解、配樂與錄音

• 進入「3. 廣播劇本編輯區」，AI 導演已將故事切分成一個個精彩場景：
  • 🎵 場景背景音樂 BGM 主題：每個場景可透過下拉選單挑選 AI 規劃的專屬配樂主題（亦可選「無」）。
  • 台詞與情緒：每一行清楚標註【角色】、【情緒指導】與【台詞內容】，隨時可自由編輯（修改後該場景會貼心標記 ● 內容已修改）。
  • 🎙 單幕錄製：點擊場景右上角的 「🎙 生成語音」（或 「🎙 重新生成」），AI 演員就會為該場景配音演繹。
  • ▶️ 當場試聽：錄音完成後，點擊 「▶️」 按鈕即可立即播放試聽該場景的聲音與配樂！
  • ✨ 安全審查小幫手：若台詞觸發敏感安全審查，點擊 「✨ 讓 AI 幫我想安全的台詞」，AI 會立即提供安全的替代台詞並支援一鍵替換。

5. 🔊 產出完整有聲書

• 所有場景確認完畢後，點擊最下方的 「🔊 產出完整有聲書」。
• 若有尚未生成的場景，系統會貼心詢問是否自動依序補齊錄音。
• 合併完成後，一部具備情緒演繹與背景音樂的完整有聲書就熱騰騰出爐了！

---

📂 我的有聲書存放在哪裡？

你的所有故事、角色設定與錄音成果，都整整齊齊收納在電腦的專屬保險箱中：

• Windows：C:\Users\你的使用者名稱\Documents\StoryForge\<故事名稱>\
• Mac：~/Documents/StoryForge/<故事名稱>/

進入該資料夾，你會看到一個名為 final_output.mp3 的檔案，這就是最終的高音質有聲書成品！你可以直接點開播放、傳到手機或分享給朋友聆聽。

---

❓ 常見問題 Q&A

Q1：需要自己安裝 ffmpeg 或其他剪輯工具嗎？
不需要！StoryForge 已經貼心內建了「自動剪刀小幫手」（static-ffmpeg），在後台全自動處理音訊拼接，完全不需要手動設定。

Q2：換到不同資料夾打開，設定需要重打嗎？
不需要！通行證與設定統一儲存在電腦的「文件/StoryForge」專屬位置，不管從哪裡啟動都能自動讀取。

Q3：我想修改某個角色的台詞或聲音，需要全部重跑嗎？
不用！StoryForge 是「以場景為單位」錄音的。如果你只想改某一幕的台詞、情緒或配樂，只要單獨重新產生該場景即可，省時又節省額度。

Q4：錄音時如果遇到台詞被安全審查阻擋怎麼辦？
別擔心！遇到阻擋時，該場景會出現「✨ 讓 AI 幫我想安全的台詞」按鈕。點擊後 AI 導演會為您構思既符合劇情的安全替代台詞，點選即可一鍵自動替換！

---

🤝 開發與參與貢獻

想了解專案架構、參與程式碼開發、或是送出 PR 協助改進嗎？
歡迎閱讀 開發者與協作者貢獻指南 (CONTRIBUTING.md)。