Metadata-Version: 2.5
Name: storyforge-studio
Version: 0.1.0
Summary: 將文字故事轉換為具備情緒、角色演繹與生動聲音的有聲書電腦軟體
Author: Jonas Cheng
Requires-Python: >=3.11
Requires-Dist: audioop-lts>=0.2.1; python_version >= '3.13'
Requires-Dist: google-genai>=0.1.0
Requires-Dist: pydub>=0.25.1
Requires-Dist: pyobjc-framework-webkit>=10.0; sys_platform == 'darwin'
Requires-Dist: pythonnet>=3.0.0; sys_platform == 'win32'
Requires-Dist: pywebview>=5.0.0
Requires-Dist: static-ffmpeg>=2.5
Description-Content-Type: text/markdown

# StoryForge 🎙️✨

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

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

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

---

## 🚀 三分鐘快速上手

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

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

- **🪟 Windows 使用者**：
  1. 在鍵盤上同時按下 `Win + X` 鍵，點選 **「終端機」** 或 **「PowerShell」**。
  2. 複製以下指令貼進黑視窗中，並按 `Enter` 執行：
     ```powershell
     powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
     ```

- **🍎 Mac 使用者**：
  1. 在鍵盤上同時按下 `Command + 空白鍵`，輸入 `Terminal` 並打開 **「終端機」**。
  2. 複製以下指令貼進終端機中，並按 `Enter` 執行：
     ```bash
     curl -LsSf https://astral.sh/uv/install.sh | sh
     ```

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

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

```bash
uvx storyforge-studio
```

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

---

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

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

1. 點擊設定畫面中 `Gemini API Key` 欄位旁的超連結，前往 [Google AI Studio](https://aistudio.google.com/) 網頁並登入您的 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)](CONTRIBUTING.md)。
