Karaoke Lyrics Processor 🎶 ✍️
Karaoke Lyrics Processor is a tool to prepare song lyrics for karaoke video production.
It processes lyrics by intelligently splitting long lines, handling parentheses, cleaning punctuation, and ensuring that each line fits within a specified maximum length. This tool is especially useful for creating karaoke tracks where timing and line length are crucial for readability.
✨ Features
Core Processing
- Smart Line Splitting: Automatically splits long lines using intelligent algorithms that prioritize commas, "and" conjunctions, and natural word boundaries
- Parentheses Handling: Properly processes lines containing parentheses, maintaining lyrical flow and handling nested parentheses
- Punctuation Cleanup: Removes unnecessary spaces before punctuation marks and fixes comma placement
- Unicode Support: Handles international characters and special Unicode spaces correctly
- Safety Mechanisms: Built-in infinite loop prevention and iteration limits for robust processing
File Format Support
- Multiple Input Formats: Supports TXT, DOCX, DOC, and RTF files
- Encoding Handling: Properly handles UTF-8 and various text encodings
- Fallback Processing: Uses multiple libraries (docx2txt, textract) for maximum compatibility
User Experience
- Clipboard Integration: Automatically copies processed lyrics to clipboard for easy pasting
- Flexible Output: Customizable output filenames and automatic naming conventions
- Debug Mode: Comprehensive logging for troubleshooting and fine-tuning
- Command Line Interface: Full-featured CLI with helpful options and error handling
Quality & Reliability
- 98% Test Coverage: Comprehensive test suite with 88 tests covering all functionality
- Edge Case Handling: Robust handling of empty files, very long words, malformed input, and unusual formatting
- Performance Tested: Memory efficient processing with performance safeguards
- Error Recovery: Graceful error handling with informative messages
🚀 Installation
To install the Karaoke Lyrics Processor, ensure you have Python 3.9 or newer in your environment.
This package is available on PyPI and can be installed using pip:
pip install karaoke-lyrics-processor
📋 Usage
Command Line Interface
Process a lyrics file with default settings:
karaoke-lyrics-processor path/to/your/lyrics.txt
Output: Creates path/to/your/lyrics (Lyrics Processed).txt with processed lyrics.
Advanced Usage Examples
# Custom output file
karaoke-lyrics-processor -o my_processed_lyrics.txt song.txt
# Custom line length (default is 36 characters)
karaoke-lyrics-processor -l 50 song.txt
# Debug mode for detailed logging
karaoke-lyrics-processor -d song.txt
# Combine all options
karaoke-lyrics-processor -d -o output.txt -l 40 input.docx
Supported Input Formats
.txt- Plain text files (UTF-8 recommended).docx- Microsoft Word documents.doc- Legacy Microsoft Word documents.rtf- Rich Text Format files
Command Line Options
usage: karaoke-lyrics-processor [-h] [-v] [-d] [-o OUTPUT] [-l LINE_LENGTH] filename
Process song lyrics to prepare them for karaoke video production
positional arguments:
filename Path to the lyrics file to process
options:
-h, --help Show help message and exit
-v, --version Show program's version number and exit
-d, --debug Enable debug mode with detailed logging
-o OUTPUT, --output OUTPUT Specify the output filename
-l LINE_LENGTH, --line_length LINE_LENGTH Maximum line length (default: 36)
🔧 Processing Features
Intelligent Line Splitting
The processor uses sophisticated algorithms to find optimal split points:
- Comma Priority: Splits at commas near the middle of long lines
- Conjunction Splitting: Uses "and" as split points when appropriate
- Word Boundaries: Respects word boundaries and avoids breaking words
- Parentheses Awareness: Handles parenthetical content intelligently
- Fallback Mechanisms: Forces splits when no natural break points exist
Text Cleaning
- Removes non-printable characters while preserving essential formatting
- Normalizes various Unicode space characters to regular spaces
- Consolidates multiple consecutive newlines
- Strips unnecessary whitespace from line beginnings and ends
Error Handling
- Graceful handling of unsupported file formats
- Recovery from encoding issues
- Protection against infinite processing loops
- Clear error messages for troubleshooting
🧪 Development & Testing
This package maintains high quality standards with comprehensive testing:
- 98% Test Coverage across all modules
- 88 Total Tests including unit, integration, and CLI tests
- Edge Case Testing for robustness
- Performance Testing to prevent regressions
- Continuous Integration with automated testing
Running Tests
# Install development dependencies
pip install pytest pytest-cov
# Run the full test suite
pytest --cov=karaoke_lyrics_processor --cov-report=html
# Run with verbose output
pytest -v
# Generate coverage report
pytest --cov-report=term-missing
🤝 Contributing
Contributions are very much welcome! This project follows best practices for maintainability:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Write tests for your changes
- Ensure tests pass and maintain >90% coverage
- Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development Setup
# Clone the repository
git clone https://github.com/nomadkaraoke/karaoke-lyrics-processor.git
cd karaoke-lyrics-processor
# Install development dependencies
pip install -e ".[dev]"
# Run tests
python run_tests.py
- This project is 100% open-source and free for anyone to use and modify as they wish
- All contributions are tested automatically via CI/CD
- Code quality is maintained through comprehensive testing and reviews
📄 License
This project is licensed under the MIT License.
💌 Contact
For questions, feature requests, or bug reports:
- Issues: GitHub Issues
- Email: Andrew Beveridge (@beveradb)
- Discussions: GitHub Discussions
Built with ❤️ for the karaoke community
Metadata
Release files for karaoke-lyrics-processor 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| karaoke_lyrics_processor-0.6.0.tar.gz | 9.3 kB | Without provenance | Details for karaoke_lyrics_processor-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| karaoke_lyrics_processor-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for karaoke_lyrics_processor-0.6.0-py3-none-any.whl |
Total release size: 20.1 kB
Release files / karaoke_lyrics_processor-0.6.0.tar.gz
| Download URL | karaoke_lyrics_processor-0.6.0.tar.gz |
|---|---|
| Size | 9.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aa97ebe5b440e8301de7517f65975a0b2f1cae0823b732a09226d4d77096f294
|
|
BLAKE2b-256 checksum How to use checksums |
f85df369042d63ae3bcbc3c74f67f83567737e41b6bfd62d1031d620bcee69be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.13
|
Release files / karaoke_lyrics_processor-0.6.0-py3-none-any.whl
| Download URL | karaoke_lyrics_processor-0.6.0-py3-none-any.whl |
|---|---|
| Size | 10.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bac7712481ba0400a8b2547ba5d97cfd48001d676e4f237c5321ab2ed0d50c64
|
|
BLAKE2b-256 checksum How to use checksums |
d239dc5a9167528e0665b14f0ca1cf2acbcc0e9e50c4983dd78b69935c87eaf0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.13
|
Security for karaoke-lyrics-processor 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.