🎙️ StoryCast AI

---

🌟 Overview

StoryCast AI is an open-source tool that automates turning online novels into audiobooks. It scrapes each chapter, cleans up the text, reads it aloud with an expressive AI voice, plays it in a built-in web player, and can export the whole story as a single .m4b audiobook file.

Completely free — no account sign-up and no third-party API key required!

---

✨ Features

• 🕷️ Smart Scraper:
  • Just paste a story link (the story's main page or chapter 1).
  • Automatically extracts chapter content using @mozilla/readability and jsdom.
  • Works with both Vietnamese novel sites (TruyenFull, Tangthuvien...) and Chinese ones (69shu, Biquge...).
  • Automatically finds the "Next chapter" button (Chương sau, 下一章) and strips noise, ads and anti-copy characters.
• 🌏 Chinese → Vietnamese translation (free):
  • Paste a link from PO18 or any Chinese novel site and pick how to translate it:
    • Convert (default): the classic Vietnamese "convert" style — longest-match lookup in the community VietPhrase dictionaries, with character names in Hán Việt (林浅 → Lâm Thiển). Traditional Chinese is simplified first (OpenCC) so it matches the dictionaries. Runs offline after a one-time ~60 MB dictionary download into data/dict/.
    • Google Dịch: smoother sentences, but names come out in pinyin (Lin Qian).
    • Không dịch: keep the original and use the Chinese voice.
  • The story title, chapter titles and full chapter text are translated, then read by the Vietnamese voice. Vietnamese stories are left untouched.
• 🌐 Browse Chinese sites in Vietnamese (Đọc web):
  • Open Đọc web in the sidebar and paste any PO18 link — home page, rankings, a book page or a chapter.
  • The whole page is converted to Vietnamese (same Convert engine, names in Hán Việt), and every link inside it opens converted too, so you can browse the site in Vietnamese.
  • Switch between Tiếng Việt, Tiếng Trung (the original page) and Song song (both side by side; following a link in one side takes the other side to the same page). /web?url=…&mode=both opens straight in side-by-side mode.
  • Each book or chapter page gets a 🎧 Tạo audio truyện này button that opens Thêm truyện with the link filled in.
  • The site's scripts are removed and the page is served with script-src 'none', so nothing from the site runs inside StoryCast. Search forms that use POST (like PO18's) are not supported.
• 🎙️ Natural multilingual AI voices (Neural TTS):
  • Automatic language detection: detects Vietnamese or Chinese from the chapter text.
  • Vietnamese: the expressive Hoài My (vi-VN-HoaiMyNeural) voice.
  • Chinese: the smooth novel-reading Xiaoxiao (zh-CN-XiaoxiaoNeural) voice.
  • Completely free, no character limits, and no API key needed.
  • Smart paragraph/sentence chunking that understands both Latin and CJK punctuation (。！？；).
• 🎧 Built-in Web Player:
  • Remembers which chapter you were on and the exact second you stopped.
  • Automatically moves on to the next chapter when one finishes.
  • Adjustable playback speed (0.75x to 2.0x).
• 📦 Full audiobook export:
  • Download individual chapters as .mp3.
  • Package the whole story into one .m4b file with chapter markers, compatible with Apple Books, Smart AudioBook Player, Voice, and more.
• ⚙️ Background Worker:
  • A background queue processes chapters one by one without freezing the UI.
  • Real-time progress tracking.
• 🗄️ Zero-Config Database:
  • Uses the SQLite built into Node.js (node:sqlite) — no database server to install.

---

🛠️ Tech Stack

Layer	Technology / Library
Framework	Next.js 16 (App Router), React 19
Language	TypeScript 5
UI	Tailwind CSS v4, Radix UI, React Icons
State management	Zustand
Text-to-Speech	msedge-tts
Parser & Scraper	@mozilla/readability, jsdom
Database	node:sqlite (native SQLite in Node.js)
Audio processing	ffmpeg

---

📋 Requirements

You need two things installed before you start:

1. Node.js >= 22.13.0 (required)

Node.js provides the node and npm commands used in every step below, and version 22.13+ is required for node:sqlite.

First, check whether you already have it:

node -v

• If it prints v22.13.0 or higher, you're good — skip to step 2.
• If it prints command not found, or a version lower than v22.13.0, install Node.js first using one of the options below.

Linux / macOS — using nvm (recommended, works on any distro):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
# close and reopen your terminal, then:
nvm install 22

Ubuntu / Debian — using apt:

sudo apt install nodejs npm -y
node -v   # must be v22.13.0 or higher

⚠️ The Node.js version in apt depends on your Ubuntu/Debian release. Older releases (e.g. Ubuntu 22.04 / 24.04) ship a version that is too old — if node -v shows lower than v22.13.0, remove it and use nvm instead.

macOS — using Homebrew:

brew install node

Windows:

winget install OpenJS.NodeJS.LTS

Or download the LTS installer from nodejs.org. Reopen your terminal after installing.

Verify the installation before continuing:

node -v   # v22.13.0 or higher
npm -v

2. ffmpeg

Needed to merge chapters into a .m4b file.

• Ubuntu/Debian: sudo apt install ffmpeg -y
• macOS: brew install ffmpeg
• Windows: winget install Gyan.FFmpeg or via Chocolatey.

---

🚀 Installation & Running

Make sure node -v works (see Requirements) before running these steps. Without Node.js, every npm command fails with npm: command not found and nothing will be running at localhost:3001.

1. Get the source code

git clone https://github.com/mochihat/storycast-ai.git
cd storycast-ai

2. Install dependencies

npm install

3. Run in development mode

npm run dev

Wait until the terminal shows ✓ Ready, then open http://localhost:3001 in your browser.

Keep this terminal open — closing it (or pressing Ctrl+C) stops the server.

StoryCast always runs on port 3001 (both npm run dev and npm start). If that port is already taken — usually by an older StoryCast you forgot to stop — it does not move to another port; it stops and prints Cổng 3001 đang bị chiếm with how to free it. See Troubleshooting.

4. Build and run in production mode (recommended)

For smoother performance and lower memory usage:

npm run build
npm start

5. Run in the background, always on (Linux)

To have StoryCast start by itself when you log in — no terminal needed, just open http://localhost:3001 — install it as a background service:

./scripts/install-service.sh

What	Command
After pulling new code (rebuild + restart)	./scripts/install-service.sh
Restart (e.g. after changing .env.local)	systemctl --user restart storycast
Stop / start	systemctl --user stop storycast / systemctl --user start storycast
Turn off auto-start	systemctl --user disable --now storycast
See its log	journalctl --user -u storycast -f

The service uses port 3001, so npm run dev will say the port is taken while it runs. Stop the service first (systemctl --user stop storycast) if you want to develop.

---

🩺 Troubleshooting

Symptom	Cause & fix
node: command not found / npm: command not found	Node.js isn't installed. Follow Requirements → Node.js, then run npm install again.
Browser says "This site can't be reached" at localhost:3001	The server isn't running. Check the terminal where you ran npm run dev for an error, and make sure it shows ✓ Ready.
No such built-in module: node:sqlite	Your Node.js is older than 22.13. Upgrade it (e.g. nvm install 22).
Cổng 3001 đang bị chiếm	StoryCast always runs on port 3001 (two copies would share one database). Another copy is probably still running: press Ctrl+C in its terminal, or run fuser -k 3001/tcp (Linux) / lsof -ti :3001 | xargs kill (macOS).
ExperimentalWarning: SQLite is an experimental feature	Just a warning, not an error — the app works normally.
The first Chinese story takes ~30 s to start	The convert dictionaries (~60 MB) are being downloaded into data/dict/. Later stories start in a few seconds. They also use ~250 MB of RAM while the server runs.
Weird errors after npm install failed earlier	Delete the node_modules folder and run npm install again.

---

📖 Usage

1. Add a story:
   • Paste the URL of chapter 1 or the story's main page (e.g. from popular sites like truyenfull).
   • Enter how many chapters you want to turn into audio.
2. Track progress:
   • The background worker scrapes and converts each chapter in turn.
   • Each chapter's status switches to ready as soon as it's done.
3. Listen:
   • Play directly from the Player bar at the bottom of the page.
   • Download individual .mp3 chapters, or click Tải cả quyển (.m4b) (download the whole book) to listen offline on your phone.

---

📂 Project Structure

storycast-ai/
├── app/                  # Next.js App Router (UI & API endpoints)
│   ├── api/              # API routes for stories, audio and downloads
│   └── page.tsx          # Main dashboard page
├── components/           # UI components (Player, Sidebar, Cover...)
├── data/                 # Local storage (gitignored)
│   ├── storycast.db      # SQLite database
│   └── audio/            # Generated mp3 files, grouped by story ID
├── lib/                  # Core logic
│   ├── book.ts           # Builds the m4b file and chapter metadata with ffmpeg
│   ├── db.ts             # node:sqlite connection and queries
│   ├── scraper.ts        # Chapter extraction and anti-copy cleanup
│   ├── convert.ts        # VietPhrase "convert" with Hán Việt names
│   ├── drm.ts            # Sec-MS-GEC v2 token required by Edge TTS
│   ├── translate.ts      # Chooses convert or Google Translate
│   ├── webpage.ts        # Converts a whole web page and routes its links back through StoryCast
│   ├── tts.ts            # Edge TTS connection and text chunking
│   └── worker.ts         # Background processing queue
├── types.ts              # TypeScript type definitions
└── public/               # Static assets

---

💾 Data & Backup

All data created while using the app lives in the data/ folder:

• data/storycast.db: the story list, chapter info and chapter text.
• data/audio/<story_id>/: the .mp3 audio files for each chapter.

💡 Tips:

• To back up: just copy the data/ folder.
• To reset everything: stop the server and delete the data/ folder.

---

🌐 Supported Sites

• Tested and optimized for: TruyenFull, Wattpad.
• PO18 (po18.tw): every book page requires a logged-in account, so StoryCast uses your own browser session:
  1. Log in at po18.tw in your browser.
  2. Open DevTools (F12) → Network, reload the page, click the first request and copy the whole value of the Cookie request header.
  3. Create a file .env.local in the project folder containing PO18_COOKIE=<the value you copied>, then restart the server.
  4. Paste the book link (https://www.po18.tw/books/<id>) or a chapter link (.../books/<id>/articles/<id>).
  • Only chapters your account can read (free chapters, or paid chapters you have bought) can be fetched.
• Other sites: StoryCast uses smart content detection (Readability) and automatically looks for "Next chapter" links, so most novel sites with standard HTML structure work well.
• Note: Sites that require logging in, or that load content through complex client-side JavaScript, may not be extractable.

---

Dictionaries used by Convert

• VietPhrase, Name, Pronouns and ChinesePhienAmWords from ducbui0/tong-hop-tu-dien — community QuickTranslator dictionaries; no license is stated.
• Traditional → simplified table TSCharacters.txt from OpenCC (Apache-2.0).

Both are pinned to a specific commit in lib/convert.ts and downloaded at runtime; they are not part of this repository.

---

⚖️ Disclaimer

• This project is built for learning, research and personal listening.
• Please respect the rights of authors, translators and the websites that publish the stories.
• Voices are provided by the public Microsoft Edge TTS service; please follow Microsoft's terms of service.

---

📄 License

Distributed under the MIT License.