Read a Markdown file such as blog.md on a fresh MacBook and produce a clean, for example, Mandarin Chinese audio file with a stable, professional voice. You can also produce English and other languages based on the settings you choose from, but the process is the same.

This guide reproduces the working setup in this folder.

Why This Path

We intentionally use edge-tts instead of ChatTTS.

Reason:

  • better consistency for long-form explanatory text
  • clearer pronunciation for non-literary content
  • less likely to insert random extra words or skip large sections
  • easier setup on macOS

Tested Result

  • Python: 3.14.0
  • Voice: zh-CN-YunyangNeural
  • Style: standard Mainland Mandarin, professional and reliable
  • Output example: blog_edge.mp3

Files In This Folder

Prerequisites

You need a working python3 command on macOS.

Check it:

python3 --version

If that fails, install Python first, then come back.

Setup

Open Terminal and go to this folder:

cd /Users/kircerta/Documents/OpenSource

Create an isolated virtual environment:

python3 -m venv .venv-edge-tts

Install the pinned dependency:

.venv-edge-tts/bin/pip install -r requirements-edge-tts.txt

Run

Use the default high-quality Mandarin voice:

.venv-edge-tts/bin/python read_blog_edge.py --input blog.md --output blog_edge.mp3 --voice zh-CN-YunyangNeural

Expected console output looks like this:

Voice: zh-CN-YunyangNeural
Rate: -5%
共 N 段，输出到: /Users/kircerta/Documents/OpenSource/blog_edge.mp3
正在合成: 1/N
...
完成

When it finishes, the result will be:

Why This Voice

Use zh-CN-YunyangNeural.

Reason:

  • standard Mainland Mandarin
  • no Taiwan accent
  • more professional than novel-style voices
  • better fit for technical writing, deep analysis, and theorem review

Recommended Usage For Technical Content

This setup is best for:

  • AI research notes
  • technical blog posts
  • system design writeups
  • theorem review and derivation explanation
  • structured analysis documents

It is intentionally not optimized for:

  • dramatic narration
  • playful delivery
  • character voices

Optional Voice Check

To list available Chinese voices:

.venv-edge-tts/bin/edge-tts --list-voices | rg 'zh-CN|zh-HK|zh-TW'

Recommended alternatives if you want to compare:

  • zh-CN-XiaoxiaoNeural
  • zh-CN-YunyangNeural
  • zh-CN-YunjianNeural

If you want standard Mandarin and a professional tone, keep using zh-CN-YunyangNeural.

Changing Speed

Default rate is slightly slowed down for clarity:

  • -5%

You can change it:

.venv-edge-tts/bin/python read_blog_edge.py --input blog.md --output blog_edge.mp3 --voice zh-CN-YunyangNeural --rate -10%

General rule:

  • slower: clearer for technical content
  • faster: better for casual listening

What The Script Does

read_blog_edge.py does four useful things:

  1. removes some Markdown noise
  2. splits long text into manageable chunks
  3. synthesizes chunk by chunk
  4. appends audio into one output MP3

This is why it behaves more reliably on long documents than a naive one-shot request.

Troubleshooting

python3: command not found

Python is not installed or not on PATH.

ModuleNotFoundError: No module named 'edge_tts'

You are not using the virtual environment Python.

Use:

.venv-edge-tts/bin/python read_blog_edge.py

The voice sounds too lively or too soft

Try:

  • zh-CN-YunyangNeural for professional tone
  • zh-CN-XiaoxiaoNeural for a cleaner female news-style tone

The text contains lots of formulas

This script removes some Markdown markers, but raw symbolic math may still sound awkward. For best results:

  • rewrite dense formulas into spoken Chinese
  • turn symbols into words
  • avoid leaving raw LaTeX in the input

One-Command Summary

If the environment is already created:

cd /Users/kircerta/Documents/OpenSource
.venv-edge-tts/bin/python read_blog_edge.py --input blog.md --output blog_edge.mp3 --voice zh-CN-YunyangNeural

That command is the exact path that produced the successful result in this workspace.