## Summary Fixes the deployment failure from PR #297 by making lyrics_transcriber a proper subpackage of karaoke_gen instead of a separate vendored library. ### Changes - Move `libs/lyrics_transcriber/` to `karaoke_gen/lyrics_transcriber/` - Update all imports from `from lyrics_transcriber.X` to `from karaoke_gen.lyrics_transcriber.X` - Simplify Dockerfile (no separate `libs/` COPY needed) - Update pyproject.toml to remove separate package entry - Update test mocks and logger names ### Why this is better - Cleaner project structure - one package containing everything - Simpler Dockerfile - just COPY karaoke_gen/ - No confusion about vendored vs internal code ## Test plan - [x] `poetry install` succeeds - [x] All imports work correctly - [x] All 2614 tests pass - [ ] Backend deployment succeeds @coderabbitai ignore Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
8.4 KiB
Plan: Deprecate python-lyrics-transcriber and Consolidate into karaoke-gen
Created: 2026-01-19 Branch: feat/sess-20260117-1643-deprecate-lyrics-transcriber Status: Draft
Overview
The python-lyrics-transcriber project was originally a standalone PyPI package. It was vendored into karaoke-gen as lyrics_transcriber_temp/ to enable faster iteration. Now that the frontend has been consolidated into karaoke-gen (lyrics review UI is part of the main frontend), maintaining lyrics-transcriber as a separate project no longer makes sense.
This plan covers:
- Updating the python-lyrics-transcriber README to redirect to karaoke-gen
- Archiving the GitHub repo
- Deprecating the PyPI package (via README update published as final version)
- Reorganizing vendored code to a permanent location in karaoke-gen
- Cleaning up unnecessary files (pyproject.toml, docs/, tests/, etc. that only made sense for a standalone package)
Requirements
- python-lyrics-transcriber GitHub repo README updated with deprecation notice
- python-lyrics-transcriber GitHub repo archived
- Final PyPI release with deprecation notice in README
- Vendored code moved from
lyrics_transcriber_temp/tolibs/lyrics_transcriber/ - Unnecessary package files removed (pyproject.toml, poetry.lock, .github/, docs/, tests/, scripts/, specs/, .cursor/, .specify/)
- All import paths continue to work (Python allows
libs/lyrics_transcriber/lyrics_transcriber/path) - Tests pass after reorganization
- karaoke-gen pyproject.toml updated for new path
Technical Approach
New Path Structure
Move the vendored code to libs/lyrics_transcriber/:
karaoke-gen/
├── libs/
│ └── lyrics_transcriber/ # Just the Python package (was lyrics_transcriber_temp/lyrics_transcriber/)
│ ├── __init__.py
│ ├── cli/
│ ├── core/
│ ├── correction/
│ ├── lyrics/
│ ├── output/
│ ├── review/
│ ├── storage/
│ ├── transcribers/
│ ├── types.py
│ └── utils/
├── karaoke_gen/
├── backend/
├── frontend/
└── ...
Why libs/lyrics_transcriber/ instead of alternatives?
libs/- Clear convention for vendored/embedded libraries, separate from main codebase- Single level -
lyrics_transcriberdirectly underlibs/, not nested (nolibs/lyrics_transcriber/lyrics_transcriber/) - Clean imports -
from karaoke_gen.lyrics_transcriber.core import ...continues to work with proper Poetry config
pyproject.toml Changes
packages = [
{ include = "karaoke_gen" },
{ include = "lyrics_transcriber", from = "libs" }, # Changed from lyrics_transcriber_temp
{ include = "backend" }
]
include = [
"karaoke_gen/nextjs_frontend/out",
"karaoke_gen/nextjs_frontend/out/**/*",
"libs/lyrics_transcriber/output/fonts/*", # Updated path
"libs/lyrics_transcriber/output/cdgmaker/images/*",
"libs/lyrics_transcriber/output/cdgmaker/transitions/*"
]
Files to Remove from Vendored Code
From current lyrics_transcriber_temp/:
pyproject.toml- Package config for standalone releasepoetry.lock- Lock file for standalone packageREADME.md- Will be replaced by deprecation noticeLICENSE- Keep MIT license in karaoke-gen root (already there)Dockerfile- Standalone container build.github/- CI/CD for standalone package.cursor/- Cursor AI config.specify/- Specify config.gitignore- Not needed (karaoke-gen has its own)docs/- Old documentation (karaoke-gen has consolidated docs)scripts/- Development scripts for standalone packagespecs/- Specification filestests/- Tests will need to be migrated or removed (see Testing Strategy)
Keep only: The actual lyrics_transcriber/ Python package directory.
Implementation Steps
Phase 1: Update and Archive External Project (Manual Steps)
- Clone python-lyrics-transcriber repo locally
- Create deprecation notice README:
# python-lyrics-transcriber (DEPRECATED) **This project has been deprecated and archived.** The lyrics transcription functionality has been consolidated into [karaoke-gen](https://github.com/nomadkaraoke/karaoke-gen). ## Migration For karaoke video generation with synchronized lyrics: - Use [karaoke-gen](https://github.com/nomadkaraoke/karaoke-gen) - the complete solution - Web app: https://gen.nomadkaraoke.com ## Historical Context This library was originally developed as a standalone tool for creating synchronized lyrics files. It has now been integrated into the karaoke-gen platform which provides a complete end-to-end solution for karaoke video generation. The last standalone version was 0.81.0. No further releases will be made to PyPI. - Publish final PyPI version (0.82.0) with deprecation notice
- Archive the GitHub repository via
gh repo archive nomadkaraoke/python-lyrics-transcriber
Phase 2: Reorganize Vendored Code in karaoke-gen
- Create
libs/directory - Move
lyrics_transcriber_temp/lyrics_transcriber/tolibs/lyrics_transcriber/ - Remove
lyrics_transcriber_temp/directory (with all its extra files) - Update
pyproject.tomlpackages and include paths - Update the one script that references
lyrics_transcriber_tempdirectly:scripts/benchmark_encoding.pyline 232: changefrom lyrics_transcriber_temp.lyrics_transcriber.output.videotofrom karaoke_gen.lyrics_transcriber.output.video
Phase 3: Verify and Test
- Run
poetry installto verify package configuration - Run
make testto ensure all tests pass - Verify imports work:
from karaoke_gen.lyrics_transcriber.core.controller import LyricsControllerResult from karaoke_gen.lyrics_transcriber.output.generator import OutputGenerator from karaoke_gen.lyrics_transcriber.types import CorrectionResult
Phase 4: Handle Tests from lyrics_transcriber
- Evaluate lyrics_transcriber tests:
- 74 test files in
lyrics_transcriber_temp/tests/ - These test the internal lyrics_transcriber library functionality
- Decision: Move critical tests to
tests/unit/lyrics_transcriber/in karaoke-gen - Skip integration/performance/manual tests that were for standalone development
- 74 test files in
Files to Create/Modify
| File | Action | Description |
|---|---|---|
libs/lyrics_transcriber/ |
Create (move) | New location for lyrics_transcriber package |
lyrics_transcriber_temp/ |
Delete | Remove old vendored location |
pyproject.toml |
Modify | Update package paths |
scripts/benchmark_encoding.py |
Modify | Update import path |
tests/unit/lyrics_transcriber/ |
Create | Migrate critical tests (optional) |
Testing Strategy
Immediate Testing
- Run
make testafter reorganization - all existing tests must pass - Verify Poetry can build/install the package correctly
Test Migration Decision
The vendored lyrics_transcriber_temp/tests/ contains 74 test files covering:
unit/correction/- Correction logic tests (important)unit/lyrics/- Lyrics provider testsunit/review/- Review server tests (less relevant - frontend consolidated)integration/- Integration testsperformance/- Performance benchmarks
Recommendation: Migrate a subset of critical unit tests, particularly:
test_corrector.py- Core correction logictest_anchor_sequence*.py- Anchor sequence matching- Handler tests in
handlers/
This keeps karaoke-gen's test suite focused while preserving coverage of critical functionality.
Open Questions
- Should lyrics_transcriber tests be migrated? Recommendation: Migrate critical unit tests only
- What's the best path for vendored code? Answer:
libs/lyrics_transcriber/ - Should we publish a final deprecation release to PyPI before archiving? Recommended: Yes, with deprecation notice
Rollback Plan
If issues arise:
- Git revert the consolidation commits
lyrics_transcriber_temp/can be restored from git history- The external python-lyrics-transcriber repo can be unarchived if needed
Notes
- The import paths like
from karaoke_gen.lyrics_transcriber.core import ...will continue to work unchanged - Only the internal project structure changes, not the API
- This is primarily a cleanup/organization task with some external repo admin work