A powerful Python library for converting plain text files (.txt) to professional EPUB eBooks with intelligent chapter detection and AI-enhanced structure analysis.
中文文档 | English
Upgrade notes: 0.2.0 Upgrade Guide
- 📚 Intelligent Chapter Detection: Automatically identifies hierarchical structure (volumes, chapters, sections) using pattern matching
- 🤖 AI-Enhanced Parsing (Optional): Integrates with OpenAI-compatible LLMs for improved chapter title generation and structure analysis
- 🎯 Resume Support: Built-in checkpoint mechanism allows resuming interrupted conversions
- 🌍 Multi-Language Support: Handles both Chinese (GB18030, GBK, UTF-8) and English text with automatic encoding detection
- 💧 Watermark Support: Optional watermark text for copyright protection
- ✅ Content Validation: Automatic word count validation ensures conversion integrity
- ⚡ Progress Tracking: Real-time progress bar with detailed status updates
- 🎨 Professional Formatting: Clean, readable EPUB output with proper CSS styling
pip install txt-to-epub-convertergit clone https://github.com/yourusername/txt-to-epub-converter.git
cd txt-to-epub-converter
pip install -e .For AI-enhanced parsing (requires OpenAI-compatible API):
pip install txt-to-epub-converter[ai]For development:
pip install txt-to-epub-converter[dev]from txt_to_epub import txt_to_epub
# Simple conversion
result = txt_to_epub(
txt_file="my_novel.txt",
epub_file="output/my_novel.epub",
title="My Novel",
author="Author Name"
)
print(f"Conversion completed: {result['output_file']}")
print(f"Chapters: {result['chapters_count']}")
print(f"Validation: {'✓ Passed' if result['validation_passed'] else '✗ Failed'}")from txt_to_epub import txt_to_epub, ParserConfig
# Custom configuration
config = ParserConfig(
# Chapter detection patterns
chapter_patterns=[
r'^第[0-9零一二三四五六七八九十百千]+章\s+.+$', # Chinese: 第1章 标题
r'^Chapter\s+\d+[:\s]+.+$' # English: Chapter 1: Title
],
# Enable AI assistance
enable_llm_assistance=True,
llm_api_key="your-api-key", # Get key from https://console.oomol.com/
llm_base_url="https://llm.oomol.com/v1",
llm_model="gpt-4o-mini",
# Watermark
enable_watermark=True,
watermark_text="© 2026 Author Name. All rights reserved.",
# Content filtering
min_chapter_length=100, # Minimum characters per chapter
max_chapter_length=50000 # Maximum characters per chapter
)
# Convert with custom config
result = txt_to_epub(
txt_file="my_book.txt",
epub_file="output/my_book.epub",
title="My Novel",
author="Author Name",
cover_image="cover.jpg", # Optional cover image
config=config,
enable_resume=True # Enable checkpoint resume
)Perfect for converting downloaded web novels with standard chapter formatting:
from txt_to_epub import txt_to_epub
result = txt_to_epub(
txt_file="web_novel.txt",
epub_file="web_novel.epub",
title="Epic Fantasy Novel",
author="Web Author"
)Handles technical books with hierarchical structure:
from txt_to_epub import txt_to_epub, ParserConfig
config = ParserConfig(
volume_patterns=[r'^Part\s+\d+[:\s]+.+$'],
chapter_patterns=[r'^Chapter\s+\d+[:\s]+.+$'],
section_patterns=[r'^\d+\.\d+\s+.+$']
)
result = txt_to_epub(
txt_file="programming_guide.txt",
epub_file="programming_guide.epub",
title="Programming Guide",
author="Tech Writer",
config=config
)Convert multiple files efficiently:
from txt_to_epub import txt_to_epub
from pathlib import Path
txt_files = Path("books").glob("*.txt")
for txt_file in txt_files:
epub_file = f"output/{txt_file.stem}.epub"
try:
result = txt_to_epub(
txt_file=str(txt_file),
epub_file=epub_file,
title=txt_file.stem.replace("_", " ").title(),
author="Collection"
)
print(f"✓ Converted: {txt_file.name}")
except Exception as e:
print(f"✗ Failed: {txt_file.name} - {e}")| Parameter | Type | Default | Description |
|---|---|---|---|
chapter_patterns |
List[str] | Built-in patterns | Regex patterns for chapter detection |
volume_patterns |
List[str] | Built-in patterns | Regex patterns for volume detection |
section_patterns |
List[str] | Built-in patterns | Regex patterns for section detection |
min_chapter_length |
int | 50 | Minimum characters per chapter |
max_chapter_length |
int | 100000 | Maximum characters per chapter |
enable_llm_assistance |
bool | False | Enable AI-enhanced parsing |
llm_api_key |
str | None | API key (recommended from https://console.oomol.com/) |
llm_base_url |
str | https://llm.oomol.com/v1 |
API base URL |
llm_model |
str | "gpt-4o-mini" | Model name |
enable_watermark |
bool | False | Enable watermark |
watermark_text |
str | None | Watermark text |
| Parameter | Type | Required | Description |
|---|---|---|---|
txt_file |
str | Yes | Input TXT file path |
epub_file |
str | Yes | Output EPUB file path |
title |
str | No | Book title (default: empty; AI metadata can infer when enabled) |
author |
str | No | Author name (default: empty; AI metadata can infer when enabled) |
cover_image |
str | No | Cover image path (PNG/JPG) |
config |
ParserConfig | No | Custom configuration |
show_progress |
bool | No | Show progress bar (default: True) |
enable_resume |
bool | No | Enable checkpoint resume (default: False) |
The converter generates EPUB files with the following structure:
output.epub
├── Volume 1: Title
│ ├── Chapter 1: Title
│ ├── Chapter 2: Title
│ └── ...
├── Volume 2: Title
│ └── ...
└── Chapter N: Title (standalone chapters without volumes)
├── Section 1.1
└── Section 1.2
When enable_llm_assistance=True:
- Smart Title Generation: Generates descriptive titles for chapters without clear titles
- Table of Contents Detection: Removes redundant TOC sections automatically
- Batch Processing: Processes multiple chapters in parallel for efficiency
- Cost Tracking: Reports API usage and costs
Example with AI:
from txt_to_epub import txt_to_epub, ParserConfig
config = ParserConfig(
enable_llm_assistance=True,
llm_api_key="sk-...",
llm_model="gpt-4o-mini", # Fast and cost-effective
fusion_image_api_url="https://your-proxy.example.com/v1/image/generate" # Optional Fusion image endpoint override
)
result = txt_to_epub(
txt_file="novel.txt",
epub_file="novel.epub",
title="My Novel",
author="Author",
config=config
)
# AI usage stats are logged automaticallyThe resume feature allows you to continue interrupted conversions:
result = txt_to_epub(
txt_file="large_book.txt",
epub_file="large_book.epub",
title="Large Book",
author="Author",
enable_resume=True # Enable checkpoint resume
)If the conversion is interrupted (Ctrl+C, crash, etc.), simply run the same command again. The converter will:
- Detect the previous state file
- Verify the source file hasn't changed
- Resume from the last processed chapter
- Clean up the state file when complete
Every conversion includes automatic validation:
=== Conversion Content Integrity Report ===
Source file: my_novel.txt
Original characters: 123,456
Converted characters: 123,450
Match rate: 99.99%
✓ Content integrity verification passed
Chinese:
第一章 标题(Traditional numbering)第1章 标题(Arabic numerals)第001章 标题(Zero-padded)Chapter 1: 标题(Mixed)
English:
Chapter 1: TitleChapter One: TitleCHAPTER 1 - TITLE1. Title
第一卷 标题/第1卷 标题(Chinese)Volume 1: Title/Book 1: Title(English)Part I: Title(Roman numerals)
Run the test suite:
# Install dev dependencies
pip install -e .[dev]
# Run tests
pytest
# Run with coverage
pytest --cov=txt_to_epub --cov-report=htmlCheck the examples directory for complete examples:
- basic_example.py - Simple conversion
- advanced_example.py - Custom configuration
- batch_convert.py - Batch processing
- README.md - Detailed example documentation
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
# Clone repository
git clone https://github.com/yourusername/txt-to-epub-converter.git
cd txt-to-epub-converter
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -e .[dev]
# Run tests
pytest
# Format code
black src/txt_to_epubThis project is licensed under the MIT License - see the LICENSE file for details.
- EbookLib - EPUB file generation
- chardet - Character encoding detection
- OpenAI - LLM assistance (optional)
- Issues: GitHub Issues
- Documentation: GitHub Wiki
- Changelog: CHANGELOG.md
- Support for more eBook formats (MOBI, PDF)
- GUI application
- Command-line interface (CLI)
- Cloud service integration
- Enhanced AI features (style analysis, content summarization)
- Multi-language UI
Made with ❤️ by the TXT to EPUB Converter Team
Star ⭐ this repository if you find it helpful!