| Name | jebasa JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Japanese ebook audio subtitle aligner - Create synchronized subtitles from Japanese audiobooks and EPUB files |
| upload_time | 2025-09-05 06:38:39 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
alignment
audio
epub
japanese
mfa
nlp
subtitles
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Jebasa (Japanese ebook audio subtitle aligner)
[](https://badge.fury.io/py/jebasa)
[](https://pypi.org/project/jebasa/)
[](https://github.com/OCboy5/jebasa/actions)
[](https://codecov.io/gh/yourusername/jebasa)
**Jebasa** is a Python package that creates synchronized subtitles from Japanese audiobooks and EPUB files using forced alignment. It handles Japanese-specific challenges like furigana annotations and morphological analysis to produce high-quality subtitle files.
## Features
- 🎵 **Audio Processing**: Convert and prepare audio files for alignment
- 📖 **Text Extraction**: Process EPUB and text files with furigana support
- 🗣️ **Dictionary Creation**: Generate custom pronunciation dictionaries
- ⚖️ **Forced Alignment**: Use Montreal Forced Aligner for precise timing
- 📝 **Subtitle Generation**: Create properly timed SRT files
- 🔄 **Complete Pipeline**: Run all stages automatically or individually
- 🇯🇵 **Japanese Optimized**: Handles furigana, tokenization, and text normalization
## Installation
### Prerequisites
- Python 3.8 or higher
- FFmpeg (for audio processing)
- Montreal Forced Aligner (for alignment)
### Install Jebasa
```bash
pip install jebasa
```
### Install System Dependencies
#### Ubuntu/Debian
```bash
sudo apt update
sudo apt install ffmpeg
pip install montreal-forced-aligner
mfa model download acoustic japanese_mfa
```
#### macOS
```bash
brew install ffmpeg
pip install montreal-forced-aligner
mfa model download acoustic japanese_mfa
```
#### Windows
```bash
choco install ffmpeg
pip install montreal-forced-aligner
mfa model download acoustic japanese_mfa
```
## Quick Start
### Basic Usage
```bash
# Run complete pipeline
jebasa run --input-dir ./my_book --output-dir ./output
# Or run individual stages
jebasa prepare-audio --input-dir ./my_book/audio --output-dir ./processed
jebasa prepare-text --input-dir ./my_book/text --output-dir ./processed
jebasa create-dictionary --input-dir ./processed --output-dir ./dictionaries
jebasa align --corpus-dir ./processed --dictionary ./dictionaries/custom.dict --output-dir ./aligned
jebasa generate-subtitles --alignment-dir ./aligned --text-dir ./processed --output-dir ./subtitles
```
### Python API
```python
from jebasa import JebasaPipeline
from jebasa.config import JebasaConfig
# Create configuration
config = JebasaConfig()
config.paths.input_dir = "./my_book"
config.paths.output_dir = "./output"
# Run pipeline
pipeline = JebasaPipeline(config)
results = pipeline.run_all()
print(f"Generated {len(results)} subtitle files")
```
## Input Requirements
### Audio Files
- Formats: MP3, M4A, WAV, FLAC, AAC
- Will be converted to 16kHz mono WAV for alignment
- Quality: Clear speech with minimal background noise
### Text Files
- Formats: EPUB, XHTML, HTML, TXT
- Japanese text with optional furigana (ruby) annotations
- Should correspond to audio content
## Configuration
Jebasa can be configured via command-line options, configuration files, or environment variables.
### Configuration File
Create a `jebasa.yaml` file:
```yaml
audio:
sample_rate: 16000
channels: 1
format: wav
text:
tokenizer: mecab
normalize_text: true
extract_furigana: true
mfa:
acoustic_model: japanese_mfa
beam: 100
retry_beam: 400
num_jobs: 4
subtitles:
max_line_length: 42
max_lines: 2
min_duration: 1.0
max_duration: 7.0
paths:
input_dir: ./input
output_dir: ./output
temp_dir: ./temp
```
### Command Line Options
```bash
jebasa run --help
jebasa prepare-audio --help
jebasa prepare-text --help
jebasa create-dictionary --help
jebasa align --help
jebasa generate-subtitles --help
```
## Examples
### Example 1: Basic Audiobook Processing
```bash
# Organize your files
mkdir my_book/{audio,text}
cp audiobook.mp3 my_book/audio/
cp book.epub my_book/text/
# Run complete pipeline
jebasa run --input-dir ./my_book --output-dir ./output
# Find your subtitles
ls output/srt/
```
### Example 2: Custom Quality Settings
```bash
# High-quality alignment with more beam search
jebasa align \
--corpus-dir ./processed \
--dictionary ./dictionaries/custom.dict \
--output-dir ./aligned \
--beam 200 \
--retry-beam 600 \
--num-jobs 8
```
### Example 3: Processing with Configuration File
```bash
# Create configuration file
cat > jebasa.yaml << EOF
audio:
sample_rate: 22050
ffmpeg_options:
acodec: pcm_s16le
text:
min_chapter_length: 500
mfa:
num_jobs: 8
beam: 150
EOF
# Use configuration file
jebasa run --config jebasa.yaml --input-dir ./my_book
```
## Advanced Usage
### Custom Audio Processing
```python
from jebasa.audio import AudioProcessor
from jebasa.config import AudioConfig
config = AudioConfig(
sample_rate=22050,
channels=1,
format="wav",
ffmpeg_options={"acodec": "pcm_s16le"}
)
processor = AudioProcessor(config)
processed_files = processor.process_audio_files(
input_dir="./audio",
output_dir="./processed"
)
```
### Custom Text Processing
```python
from jebasa.text import TextProcessor
from jebasa.config import TextConfig
config = TextConfig(
tokenizer="mecab",
normalize_text=True,
extract_furigana=True
)
processor = TextProcessor(config)
processed_files = processor.process_text_files(
input_dir="./text",
output_dir="./processed"
)
```
### Pipeline Stages
```python
from jebasa.pipeline import JebasaPipeline
from jebasa.config import JebasaConfig
config = JebasaConfig()
pipeline = JebasaPipeline(config)
# Run individual stages
audio_files = pipeline.prepare_audio()
text_files = pipeline.prepare_text()
dictionary = pipeline.create_dictionary()
alignments = pipeline.run_alignment()
subtitles = pipeline.generate_subtitles()
```
## Troubleshooting
### Common Issues
1. **FFmpeg not found**
```
Error: FFmpeg not found. Please install FFmpeg.
```
Solution: Install FFmpeg using your system's package manager.
2. **MFA model not found**
```
Error: Acoustic model 'japanese_mfa' not found
```
Solution: Download the model with `mfa model download acoustic japanese_mfa`
3. **Poor alignment quality**
- Check audio quality (clear speech, minimal noise)
- Verify text matches audio content
- Try adjusting beam search parameters
- Check pronunciation dictionary coverage
4. **Memory issues during alignment**
- Reduce `--num-jobs` parameter
- Process files in smaller batches
- Ensure sufficient RAM (8GB+ recommended)
### Getting Help
- Check the [documentation](https://jebasa.readthedocs.io)
- Report issues on [GitHub](https://github.com/OCboy5/jebasa/issues)
- Join our [discussion forum](https://github.com/OCboy5/jebasa/discussions)
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Montreal Forced Aligner](https://montreal-forced-aligner.readthedocs.io/) for alignment
- [fugashi](https://github.com/polm/fugashi) for Japanese tokenization
- [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/) for HTML/XML parsing
## Citation
If you use Jebasa in your research, please cite:
```bibtex
@software{jebasa,
title={Jebasa: Japanese ebook audio subtitle aligner},
author={Your Name},
year={2024},
url={https://github.com/OCboy5/jebasa}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "jebasa",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "alignment, audio, epub, japanese, mfa, nlp, subtitles",
"author": null,
"author_email": "OCboy5 <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/aa/61/1df0ab66c27cae9ca8fa1bbe45a616b760030e633f2d6750b5e3a0fe60ef/jebasa-0.1.1.tar.gz",
"platform": null,
"description": "# Jebasa (Japanese ebook audio subtitle aligner)\n\n[](https://badge.fury.io/py/jebasa)\n[](https://pypi.org/project/jebasa/)\n[](https://github.com/OCboy5/jebasa/actions)\n[](https://codecov.io/gh/yourusername/jebasa)\n\n**Jebasa** is a Python package that creates synchronized subtitles from Japanese audiobooks and EPUB files using forced alignment. It handles Japanese-specific challenges like furigana annotations and morphological analysis to produce high-quality subtitle files.\n\n## Features\n\n- \ud83c\udfb5 **Audio Processing**: Convert and prepare audio files for alignment\n- \ud83d\udcd6 **Text Extraction**: Process EPUB and text files with furigana support\n- \ud83d\udde3\ufe0f **Dictionary Creation**: Generate custom pronunciation dictionaries\n- \u2696\ufe0f **Forced Alignment**: Use Montreal Forced Aligner for precise timing\n- \ud83d\udcdd **Subtitle Generation**: Create properly timed SRT files\n- \ud83d\udd04 **Complete Pipeline**: Run all stages automatically or individually\n- \ud83c\uddef\ud83c\uddf5 **Japanese Optimized**: Handles furigana, tokenization, and text normalization\n\n## Installation\n\n### Prerequisites\n\n- Python 3.8 or higher\n- FFmpeg (for audio processing)\n- Montreal Forced Aligner (for alignment)\n\n### Install Jebasa\n\n```bash\npip install jebasa\n```\n\n### Install System Dependencies\n\n#### Ubuntu/Debian\n```bash\nsudo apt update\nsudo apt install ffmpeg\npip install montreal-forced-aligner\nmfa model download acoustic japanese_mfa\n```\n\n#### macOS\n```bash\nbrew install ffmpeg\npip install montreal-forced-aligner\nmfa model download acoustic japanese_mfa\n```\n\n#### Windows\n```bash\nchoco install ffmpeg\npip install montreal-forced-aligner\nmfa model download acoustic japanese_mfa\n```\n\n## Quick Start\n\n### Basic Usage\n\n```bash\n# Run complete pipeline\njebasa run --input-dir ./my_book --output-dir ./output\n\n# Or run individual stages\njebasa prepare-audio --input-dir ./my_book/audio --output-dir ./processed\njebasa prepare-text --input-dir ./my_book/text --output-dir ./processed\njebasa create-dictionary --input-dir ./processed --output-dir ./dictionaries\njebasa align --corpus-dir ./processed --dictionary ./dictionaries/custom.dict --output-dir ./aligned\njebasa generate-subtitles --alignment-dir ./aligned --text-dir ./processed --output-dir ./subtitles\n```\n\n### Python API\n\n```python\nfrom jebasa import JebasaPipeline\nfrom jebasa.config import JebasaConfig\n\n# Create configuration\nconfig = JebasaConfig()\nconfig.paths.input_dir = \"./my_book\"\nconfig.paths.output_dir = \"./output\"\n\n# Run pipeline\npipeline = JebasaPipeline(config)\nresults = pipeline.run_all()\n\nprint(f\"Generated {len(results)} subtitle files\")\n```\n\n## Input Requirements\n\n### Audio Files\n- Formats: MP3, M4A, WAV, FLAC, AAC\n- Will be converted to 16kHz mono WAV for alignment\n- Quality: Clear speech with minimal background noise\n\n### Text Files\n- Formats: EPUB, XHTML, HTML, TXT\n- Japanese text with optional furigana (ruby) annotations\n- Should correspond to audio content\n\n## Configuration\n\nJebasa can be configured via command-line options, configuration files, or environment variables.\n\n### Configuration File\n\nCreate a `jebasa.yaml` file:\n\n```yaml\naudio:\n sample_rate: 16000\n channels: 1\n format: wav\n\ntext:\n tokenizer: mecab\n normalize_text: true\n extract_furigana: true\n\nmfa:\n acoustic_model: japanese_mfa\n beam: 100\n retry_beam: 400\n num_jobs: 4\n\nsubtitles:\n max_line_length: 42\n max_lines: 2\n min_duration: 1.0\n max_duration: 7.0\n\npaths:\n input_dir: ./input\n output_dir: ./output\n temp_dir: ./temp\n```\n\n### Command Line Options\n\n```bash\njebasa run --help\njebasa prepare-audio --help\njebasa prepare-text --help\njebasa create-dictionary --help\njebasa align --help\njebasa generate-subtitles --help\n```\n\n## Examples\n\n### Example 1: Basic Audiobook Processing\n\n```bash\n# Organize your files\nmkdir my_book/{audio,text}\ncp audiobook.mp3 my_book/audio/\ncp book.epub my_book/text/\n\n# Run complete pipeline\njebasa run --input-dir ./my_book --output-dir ./output\n\n# Find your subtitles\nls output/srt/\n```\n\n### Example 2: Custom Quality Settings\n\n```bash\n# High-quality alignment with more beam search\njebasa align \\\n --corpus-dir ./processed \\\n --dictionary ./dictionaries/custom.dict \\\n --output-dir ./aligned \\\n --beam 200 \\\n --retry-beam 600 \\\n --num-jobs 8\n```\n\n### Example 3: Processing with Configuration File\n\n```bash\n# Create configuration file\ncat > jebasa.yaml << EOF\naudio:\n sample_rate: 22050\n ffmpeg_options:\n acodec: pcm_s16le\n\ntext:\n min_chapter_length: 500\n\nmfa:\n num_jobs: 8\n beam: 150\nEOF\n\n# Use configuration file\njebasa run --config jebasa.yaml --input-dir ./my_book\n```\n\n## Advanced Usage\n\n### Custom Audio Processing\n\n```python\nfrom jebasa.audio import AudioProcessor\nfrom jebasa.config import AudioConfig\n\nconfig = AudioConfig(\n sample_rate=22050,\n channels=1,\n format=\"wav\",\n ffmpeg_options={\"acodec\": \"pcm_s16le\"}\n)\n\nprocessor = AudioProcessor(config)\nprocessed_files = processor.process_audio_files(\n input_dir=\"./audio\",\n output_dir=\"./processed\"\n)\n```\n\n### Custom Text Processing\n\n```python\nfrom jebasa.text import TextProcessor\nfrom jebasa.config import TextConfig\n\nconfig = TextConfig(\n tokenizer=\"mecab\",\n normalize_text=True,\n extract_furigana=True\n)\n\nprocessor = TextProcessor(config)\nprocessed_files = processor.process_text_files(\n input_dir=\"./text\",\n output_dir=\"./processed\"\n)\n```\n\n### Pipeline Stages\n\n```python\nfrom jebasa.pipeline import JebasaPipeline\nfrom jebasa.config import JebasaConfig\n\nconfig = JebasaConfig()\npipeline = JebasaPipeline(config)\n\n# Run individual stages\naudio_files = pipeline.prepare_audio()\ntext_files = pipeline.prepare_text()\ndictionary = pipeline.create_dictionary()\nalignments = pipeline.run_alignment()\nsubtitles = pipeline.generate_subtitles()\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **FFmpeg not found**\n ```\n Error: FFmpeg not found. Please install FFmpeg.\n ```\n Solution: Install FFmpeg using your system's package manager.\n\n2. **MFA model not found**\n ```\n Error: Acoustic model 'japanese_mfa' not found\n ```\n Solution: Download the model with `mfa model download acoustic japanese_mfa`\n\n3. **Poor alignment quality**\n - Check audio quality (clear speech, minimal noise)\n - Verify text matches audio content\n - Try adjusting beam search parameters\n - Check pronunciation dictionary coverage\n\n4. **Memory issues during alignment**\n - Reduce `--num-jobs` parameter\n - Process files in smaller batches\n - Ensure sufficient RAM (8GB+ recommended)\n\n### Getting Help\n\n- Check the [documentation](https://jebasa.readthedocs.io)\n- Report issues on [GitHub](https://github.com/OCboy5/jebasa/issues)\n- Join our [discussion forum](https://github.com/OCboy5/jebasa/discussions)\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [Montreal Forced Aligner](https://montreal-forced-aligner.readthedocs.io/) for alignment\n- [fugashi](https://github.com/polm/fugashi) for Japanese tokenization\n- [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/) for HTML/XML parsing\n\n## Citation\n\nIf you use Jebasa in your research, please cite:\n\n```bibtex\n@software{jebasa,\n title={Jebasa: Japanese ebook audio subtitle aligner},\n author={Your Name},\n year={2024},\n url={https://github.com/OCboy5/jebasa}\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Japanese ebook audio subtitle aligner - Create synchronized subtitles from Japanese audiobooks and EPUB files",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/OCboy5/jebasa/issues",
"Documentation": "https://jebasa.readthedocs.io",
"Homepage": "https://github.com/OCboy5/jebasa",
"Repository": "https://github.com/OCboy5/jebasa"
},
"split_keywords": [
"alignment",
" audio",
" epub",
" japanese",
" mfa",
" nlp",
" subtitles"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a348bb568834a08a0df47965bd7b05ddc1b632c41a6ca2533d59557cb09ef965",
"md5": "17f89cc8efdc84b6d69bffb124b578aa",
"sha256": "771e07e8c5290e6e822427f8b40b6126468833f6476597e38bb6031133144bc1"
},
"downloads": -1,
"filename": "jebasa-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "17f89cc8efdc84b6d69bffb124b578aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 38438,
"upload_time": "2025-09-05T06:38:38",
"upload_time_iso_8601": "2025-09-05T06:38:38.587202Z",
"url": "https://files.pythonhosted.org/packages/a3/48/bb568834a08a0df47965bd7b05ddc1b632c41a6ca2533d59557cb09ef965/jebasa-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "aa611df0ab66c27cae9ca8fa1bbe45a616b760030e633f2d6750b5e3a0fe60ef",
"md5": "87d88122c41118f092286b98033ca373",
"sha256": "aa460415ebd7e66d9ee90a356084c434f2beb4eabb5df0d9de11f905ae9f865d"
},
"downloads": -1,
"filename": "jebasa-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "87d88122c41118f092286b98033ca373",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 56153,
"upload_time": "2025-09-05T06:38:39",
"upload_time_iso_8601": "2025-09-05T06:38:39.869904Z",
"url": "https://files.pythonhosted.org/packages/aa/61/1df0ab66c27cae9ca8fa1bbe45a616b760030e633f2d6750b5e3a0fe60ef/jebasa-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 06:38:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OCboy5",
"github_project": "jebasa",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jebasa"
}
