🎙️ NeuralCast

轻量级本地AI播客自动化生成引擎
Lightweight Local AI Podcast Automation Engine

简体中文 · 繁體中文 · English

---

🎉 项目介绍 | Project Introduction

简体中文

NeuralCast 是一款轻量级本地AI播客自动化生成引擎，能够将 Markdown、纯文本、网页 URL 等多种格式的内容自动转换为带有多说话人、背景音乐、章节标记的专业播客音频。

解决的痛点：

• 🎯 播客制作门槛高，需要专业录音设备和后期制作技能
• 🎯 手动分配说话人角色、调节语速音调耗时耗力
• 🎯 现有工具依赖云端服务，存在隐私泄露风险
• 🎯 缺乏从文本到完整播客的一站式自动化解决方案

自研差异化亮点：

• 🚀 零重量级依赖：纯 Python 实现，核心功能仅需 edge-tts，无需 Node.js 或大型框架
• 🚀 5种内置播客模板：访谈、故事、新闻、科技、单人，一键生成不同风格播客
• 🚀 智能内容解析：自动识别 Markdown 结构，智能分配说话人角色
• 🚀 双 TTS 后端：Edge TTS（在线高质量）+ Pyttsx3（离线备用），灵活切换
• 🚀 本地优先：所有处理在本地完成，保护用户隐私

灵感来源： 受 GitHub Trending 热门 TTS 项目启发，聚焦于"从文本到完整播客"的自动化链路，而非单纯的语音合成。

---

🎉 項目介紹 | Project Introduction

繁體中文

NeuralCast 是一款輕量級本地AI播客自動化生成引擎，能夠將 Markdown、純文字、網頁 URL 等多種格式的內容自動轉換為帶有多說話人、背景音樂、章節標記的專業播客音頻。

解決的痛點：

• 🎯 播客製作門檻高，需要專業錄音設備和後期製作技能
• 🎯 手動分配說話人角色、調節語速音調耗時耗力
• 🎯 現有工具依賴雲端服務，存在隱私洩露風險
• 🎯 缺乏從文字到完整播客的一站式自動化解決方案

自研差異化亮點：

• 🚀 零重量級依賴：純 Python 實現，核心功能僅需 edge-tts，無需 Node.js 或大型框架
• 🚀 5種內建播客模板：訪談、故事、新聞、科技、單人，一鍵生成不同風格播客
• 🚀 智慧內容解析：自動識別 Markdown 結構，智慧分配說話人角色
• 🚀 雙 TTS 後端：Edge TTS（線上高品質）+ Pyttsx3（離線備用），靈活切換
• 🚀 本地優先：所有處理在本地完成，保護用戶隱私

靈感來源： 受 GitHub Trending 熱門 TTS 專案啟發，聚焦於「從文字到完整播客」的自動化鏈路，而非單純的語音合成。

---

🎉 Project Introduction

NeuralCast is a lightweight local AI podcast automation engine that converts Markdown, plain text, web URLs, and other content formats into professional podcast audio with multiple speakers, background music, and chapter markers.

Pain Points Solved:

• 🎯 High barrier to podcast creation — requires professional recording equipment and post-production skills
• 🎯 Manual speaker role assignment and voice tuning is time-consuming
• 🎯 Existing tools rely on cloud services, raising privacy concerns
• 🎯 Lack of an end-to-end automated solution from text to complete podcast

Differentiation Highlights:

• 🚀 Zero Heavy Dependencies: Pure Python implementation, only requires edge-tts for core features — no Node.js or heavy frameworks
• 🚀 5 Built-in Podcast Templates: Interview, Story, News, Tech, Solo — generate different podcast styles with one command
• 🚀 Smart Content Parsing: Automatically recognizes Markdown structure and intelligently assigns speaker roles
• 🚀 Dual TTS Backend: Edge TTS (online, high-quality) + Pyttsx3 (offline fallback) with seamless switching
• 🚀 Local-First: All processing happens locally, protecting user privacy

Inspiration: Inspired by trending TTS projects on GitHub Trending, focusing on the automated pipeline from "text to complete podcast" rather than just speech synthesis.

---

✨ 核心特性 | Core Features

简体中文

特性	描述
🎙️ 多说话人播客	支持 host/guest/narrator/expert 等多种角色，自动或手动分配声音
📝 智能内容解析	支持 Markdown、纯文本、URL、HTML 四种输入格式，自动提取结构
🎨 5种播客模板	访谈（interview）、故事（story）、新闻（news）、科技（tech）、单人（solo）
🔊 双TTS后端	Edge TTS 在线高质量合成 + Pyttsx3 离线备用，灵活切换
🎵 背景音乐混合	支持添加背景音乐，可调节音量，自动淡入淡出
📑 章节标记	自动生成章节标记，支持 JSON/CSV/M4B/Audacity 多格式导出
🌍 多语言支持	内置中文、英文、日文、韩文声音预设，覆盖主流语言
⚡ 语速/音调控制	支持调节语速（0.5x-2.0x）和音调（-20 到 +20）
🖥️ 精美CLI	基于 Rich 的彩色终端输出，实时进度显示
🧪 101个单元测试	完善的测试覆盖，确保代码质量

繁體中文

特性	描述
🎙️ 多說話人播客	支援 host/guest/narrator/expert 等多種角色，自動或手動分配聲音
📝 智慧內容解析	支援 Markdown、純文字、URL、HTML 四種輸入格式，自動提取結構
🎨 5種播客模板	訪談（interview）、故事（story）、新聞（news）、科技（tech）、單人（solo）
🔊 雙TTS後端	Edge TTS 線上高品質合成 + Pyttsx3 離線備用，靈活切換
🎵 背景音樂混合	支援添加背景音樂，可調節音量，自動淡入淡出
📑 章節標記	自動生成章節標記，支援 JSON/CSV/M4B/Audacity 多格式匯出
🌍 多語言支援	內建中文、英文、日文、韓文聲音預設，覆蓋主流語言
⚡ 語速/音調控制	支援調節語速（0.5x-2.0x）和音調（-20 到 +20）
🖥️ 精美CLI	基於 Rich 的彩色終端輸出，即時進度顯示
🧪 101個單元測試	完善的測試覆蓋，確保程式碼品質

English

Feature	Description
🎙️ Multi-Speaker Podcast	Support for host/guest/narrator/expert roles with automatic or manual voice assignment
📝 Smart Content Parsing	Parse Markdown, plain text, URLs, and HTML with automatic structure extraction
🎨 5 Podcast Templates	Interview, Story, News, Tech, Solo — one command for different podcast styles
🔊 Dual TTS Backend	Edge TTS (online, high-quality) + Pyttsx3 (offline fallback) with seamless switching
🎵 Background Music Mixing	Add background music with adjustable volume and automatic fade in/out
📑 Chapter Markers	Auto-generate chapter markers with JSON/CSV/M4B/Audacity export
🌍 Multi-Language Support	Built-in voice presets for Chinese, English, Japanese, Korean
⚡ Speed/Pitch Control	Adjustable speech rate (0.5x-2.0x) and pitch (-20 to +20)
🖥️ Beautiful CLI	Rich-based colorful terminal output with real-time progress display
🧪 101 Unit Tests	Comprehensive test coverage ensuring code quality

---

🚀 快速开始 | Quick Start

简体中文

环境要求：

• Python 3.8 或更高版本
• pip 包管理器
• （可选）ffmpeg 用于高级音频处理

安装：

# 克隆仓库
git clone https://github.com/gitstq/NeuralCast.git
cd NeuralCast

# 安装依赖
pip install -r requirements.txt

# 或者使用 pip 安装（开发模式）
pip install -e .

快速使用：

# 从 Markdown 文件生成播客
neuralcast generate -i article.md -o podcast.mp3

# 使用访谈模板（双人对话风格）
neuralcast generate -i article.md -t interview -o podcast.mp3

# 使用科技播客模板（主持人+专家）
neuralcast generate -i tech_news.md -t tech -o tech_podcast.mp3

# 添加背景音乐
neuralcast generate -i article.md -b bgm.mp3 --bgm-volume 0.15 -o podcast.mp3

# 自定义说话人声音
neuralcast generate -i article.md -v "host:zh-CN-YunxiNeural,guest:zh-CN-XiaoyiNeural"

# 调节语速和音调
neuralcast generate -i article.md --speed 1.2 --pitch 5 -o podcast.mp3

# 从 URL 生成播客
neuralcast generate -i "https://example.com/article" -o podcast.mp3

# 直接输入文本
neuralcast generate -i "今天我们来聊聊人工智能的最新发展" -o podcast.mp3

# 列出所有可用声音
neuralcast list-voices -l zh

# 查看内置模板
neuralcast templates

# 查看版本信息
neuralcast version

繁體中文

環境要求：

• Python 3.8 或更高版本
• pip 套件管理器
• （可選）ffmpeg 用於高階音訊處理

安裝：

# 克隆倉庫
git clone https://github.com/gitstq/NeuralCast.git
cd NeuralCast

# 安裝依賴
pip install -r requirements.txt

# 或者使用 pip 安裝（開發模式）
pip install -e .

快速使用：

# 從 Markdown 檔案生成播客
neuralcast generate -i article.md -o podcast.mp3

# 使用訪談模板（雙人對話風格）
neuralcast generate -i article.md -t interview -o podcast.mp3

# 使用科技播客模板（主持人+專家）
neuralcast generate -i tech_news.md -t tech -o tech_podcast.mp3

# 添加背景音樂
neuralcast generate -i article.md -b bgm.mp3 --bgm-volume 0.15 -o podcast.mp3

# 自訂說話人聲音
neuralcast generate -i article.md -v "host:zh-CN-YunxiNeural,guest:zh-CN-XiaoyiNeural"

# 調節語速和音調
neuralcast generate -i article.md --speed 1.2 --pitch 5 -o podcast.mp3

# 從 URL 生成播客
neuralcast generate -i "https://example.com/article" -o podcast.mp3

# 直接輸入文字
neuralcast generate -i "今天我們來聊聊人工智慧的最新發展" -o podcast.mp3

# 列出所有可用聲音
neuralcast list-voices -l zh

# 查看內建模板
neuralcast templates

# 查看版本資訊
neuralcast version

English

Prerequisites:

• Python 3.8 or higher
• pip package manager
• (Optional) ffmpeg for advanced audio processing

Installation:

# Clone the repository
git clone https://github.com/gitstq/NeuralCast.git
cd NeuralCast

# Install dependencies
pip install -r requirements.txt

# Or install in development mode
pip install -e .

Quick Usage:

# Generate podcast from a Markdown file
neuralcast generate -i article.md -o podcast.mp3

# Use interview template (two-person dialogue style)
neuralcast generate -i article.md -t interview -o podcast.mp3

# Use tech podcast template (host + expert)
neuralcast generate -i tech_news.md -t tech -o tech_podcast.mp3

# Add background music
neuralcast generate -i article.md -b bgm.mp3 --bgm-volume 0.15 -o podcast.mp3

# Custom voice mapping
neuralcast generate -i article.md -v "host:en-US-GuyNeural,guest:en-US-JaneNeural"

# Adjust speed and pitch
neuralcast generate -i article.md --speed 1.2 --pitch 5 -o podcast.mp3

# Generate from URL
neuralcast generate -i "https://example.com/article" -o podcast.mp3

# Direct text input
neuralcast generate -i "Today let's talk about the latest developments in AI" -o podcast.mp3

# List all available voices
neuralcast list-voices -l en

# View built-in templates
neuralcast templates

# Show version info
neuralcast version

---

📖 详细使用指南 | Detailed Guide

简体中文

播客模板说明

模板	说明	说话人	适用场景
interview	访谈播客	host + guest	人物访谈、对话类内容
story	故事播客	narrator	故事讲述、小说朗读
news	新闻播客	anchor + reporter	新闻播报、资讯类内容
tech	科技播客	host + expert	科技讨论、教程讲解
solo	单人播客	narrator	个人观点、日记随笔

CLI 完整参数

neuralcast generate -i <输入> -o <输出> [选项]

选项:
  -i, --input         输入源（文件路径、URL 或直接文本）
  -o, --output        输出文件路径（默认: output.mp3）
  -t, --template      播客模板（interview/story/news/tech/solo）
  -v, --voices        说话人声音映射（如 "host:声音1,guest:声音2"）
  -b, --bgm           背景音乐文件路径
  --bgm-volume        背景音量（0.0-1.0，默认: 0.15）
  --speed             语速（0.5-2.0，默认: 1.0）
  --pitch             音调（-20 到 +20，默认: 0）
  --format            输出格式（mp3/wav/ogg，默认: mp3）
  --chapters          启用章节标记
  --backend           TTS 后端（edge/pyttsx3，默认: edge）
  -l, --language      语言（zh/en/ja/ko，默认: zh）
  --no-color          禁用彩色输出

Markdown 输入示例

# 人工智能的未来

## 什么是大语言模型？

大语言模型（LLM）是一种基于深度学习的自然语言处理模型，
它能够理解和生成人类语言。

## 应用场景

- 智能客服
- 内容创作
- 代码生成
- 知识问答

💡 提示：使用 # 标题会自动生成章节标记，不同层级的标题会分配给不同的说话人。

繁體中文

播客模板說明

模板	說明	說話人	適用場景
interview	訪談播客	host + guest	人物訪談、對話類內容
story	故事播客	narrator	故事講述、小說朗讀
news	新聞播客	anchor + reporter	新聞播報、資訊類內容
tech	科技播客	host + expert	科技討論、教程講解
solo	單人播客	narrator	個人觀點、日記隨筆

Markdown 輸入範例

# 人工智慧的未來

## 什麼是大語言模型？

大語言模型（LLM）是一種基於深度學習的自然語言處理模型，
它能夠理解和生成人類語言。

## 應用場景

- 智慧客服
- 內容創作
- 程式碼生成
- 知識問答

💡 提示：使用 # 標題會自動生成章節標記，不同層級的標題會分配給不同的說話人。

English

Template Reference

Template	Description	Speakers	Best For
interview	Interview podcast	host + guest	Interviews, dialogues
story	Story podcast	narrator	Storytelling, audiobooks
news	News podcast	anchor + reporter	News broadcasts, updates
tech	Tech podcast	host + expert	Tech discussions, tutorials
solo	Solo podcast	narrator	Personal opinions, journaling

Markdown Input Example

# The Future of AI

## What are Large Language Models?

Large Language Models (LLMs) are deep learning-based NLP models
that can understand and generate human language.

## Use Cases

- Customer Service
- Content Creation
- Code Generation
- Knowledge Q&A

💡 Tip: # headings automatically generate chapter markers, and different heading levels are assigned to different speakers.

---

💡 设计思路与迭代规划 | Design Philosophy & Roadmap

简体中文

设计理念：

• 🎯 本地优先：所有数据处理在本地完成，不依赖任何云服务，保护用户隐私
• 🎯 模块化架构：解析器、引擎、混合器、模板系统完全解耦，便于独立扩展
• 🎯 渐进式依赖：核心功能仅需 edge-tts，pydub 等作为可选依赖按需安装
• 🎯 开发者友好：完整的 CLI 接口、类型注解、单元测试，易于集成到自动化流程

技术选型原因：

• Edge TTS：微软免费在线 TTS 服务，声音质量高，支持多语言，无需 API Key
• Pyttsx3：纯离线 TTS 引擎，作为网络不可用时的后备方案
• Rich：Python 终端美化库，提供进度条、彩色输出等用户体验增强
• pydub：音频处理库，用于背景音乐混合、格式转换等高级功能

后续迭代计划：

• 🔄 支持 SSML 语音合成标记语言
• 🔄 添加语音克隆功能（基于参考音频）
• 🔄 支持更多 TTS 后端（Coqui TTS、Bark 等）
• 🔄 添加 Web UI 管理界面
• 🔄 支持播客 RSS Feed 自动生成
• 🔄 添加音频后处理（降噪、均衡器）
• 🔄 支持批量生成（从文件夹/RSS 源）

English

Design Philosophy:

• 🎯 Local-First: All data processing happens locally — no cloud dependencies, protecting user privacy
• 🎯 Modular Architecture: Parser, engine, mixer, and template system are fully decoupled for independent extension
• 🎯 Progressive Dependencies: Core features only need edge-tts; pydub and others are optional
• 🎯 Developer-Friendly: Complete CLI, type annotations, unit tests — easy to integrate into automation pipelines

Tech Stack Choices:

• Edge TTS: Microsoft's free online TTS service — high quality, multi-language, no API key required
• Pyttsx3: Pure offline TTS engine as fallback when network is unavailable
• Rich: Terminal beautification library for progress bars, colored output, and UX enhancements
• pydub: Audio processing library for background music mixing, format conversion, and advanced features

Roadmap:

• 🔄 SSML (Speech Synthesis Markup Language) support
• 🔄 Voice cloning from reference audio
• 🔄 More TTS backends (Coqui TTS, Bark, etc.)
• 🔄 Web UI management interface
• 🔄 Automatic podcast RSS Feed generation
• 🔄 Audio post-processing (noise reduction, EQ)
• 🔄 Batch generation (from folders / RSS feeds)

---

📦 打包与部署指南 | Packaging & Deployment

简体中文

作为 Python 包安装：

# 从 PyPI 安装（未来发布后）
pip install neuralcast

# 从源码安装
git clone https://github.com/gitstq/NeuralCast.git
cd NeuralCast
pip install -e .

安装开发依赖：

pip install -r requirements-dev.txt

运行测试：

# 运行全部测试
pytest

# 运行测试并查看覆盖率
pytest --cov=neuralcast

# 运行特定测试文件
pytest tests/test_parser.py

兼容环境：

• ✅ Python 3.8+
• ✅ Windows / macOS / Linux
• ✅ （可选）ffmpeg 用于高级音频处理

English

Install as Python Package:

# From PyPI (after future release)
pip install neuralcast

# From source
git clone https://github.com/gitstq/NeuralCast.git
cd NeuralCast
pip install -e .

Install Dev Dependencies:

pip install -r requirements-dev.txt

Run Tests:

# Run all tests
pytest

# Run tests with coverage
pytest --cov=neuralcast

# Run specific test file
pytest tests/test_parser.py

Compatible Environments:

• ✅ Python 3.8+
• ✅ Windows / macOS / Linux
• ✅ (Optional) ffmpeg for advanced audio processing

---

🤝 贡献指南 | Contributing

简体中文

欢迎贡献！请遵循以下步骤：

1. 🍴 Fork 本仓库
2. 🌿 创建特性分支：git checkout -b feature/amazing-feature
3. 💾 提交更改：git commit -m 'feat: add amazing feature'
4. 📤 推送分支：git push origin feature/amazing-feature
5. 🎉 提交 Pull Request

提交规范：

• feat: 新增功能
• fix: 修复问题
• docs: 文档更新
• refactor: 代码重构
• test: 测试相关
• chore: 构建/工具变更

English

Contributions are welcome! Please follow these steps:

1. 🍴 Fork this repository
2. 🌿 Create a feature branch: git checkout -b feature/amazing-feature
3. 💾 Commit your changes: git commit -m 'feat: add amazing feature'
4. 📤 Push the branch: git push origin feature/amazing-feature
5. 🎉 Submit a Pull Request

Commit Convention:

• feat: New feature
• fix: Bug fix
• docs: Documentation update
• refactor: Code refactoring
• test: Test related
• chore: Build/tooling changes

---

📄 开源协议 | License

本项目采用 MIT License 开源协议。

This project is licensed under the MIT License.

---

Made with ❤️ by gitstq