From 598798d9dee47f16311e3954b9f698752a4787a2 Mon Sep 17 00:00:00 2001 From: mbrucedogs Date: Mon, 28 Jul 2025 14:15:51 -0500 Subject: [PATCH] Signed-off-by: mbrucedogs --- PRD.md | 13 +- cli/__pycache__/matching.cpython-313.pyc | Bin 12970 -> 14193 bytes cli/commands.txt | 262 +++++++++++++++++++++++ cli/main.py | 1 + 4 files changed, 275 insertions(+), 1 deletion(-) create mode 100644 cli/commands.txt diff --git a/PRD.md b/PRD.md index 4934a4a..d233539 100644 --- a/PRD.md +++ b/PRD.md @@ -48,16 +48,26 @@ These principles are fundamental to the project's long-term success and must be - **PRD.md Updates:** Any changes to project requirements, architecture, or functionality must be reflected in this document - **README.md Updates:** User-facing features, installation instructions, or usage changes must be documented +- **CLI Commands Documentation:** All CLI functionality, options, and usage examples must be documented in `cli/commands.txt` - **Code Comments:** Significant logic changes should include inline documentation - **API Documentation:** New endpoints, functions, or interfaces must be documented **Documentation Update Checklist:** - [ ] Update PRD.md with any architectural or requirement changes - [ ] Update README.md with new features, installation steps, or usage instructions +- [ ] Update `cli/commands.txt` with any new CLI options, examples, or functionality changes - [ ] Add inline comments for complex logic or business rules - [ ] Update any configuration examples or file structure documentation - [ ] Review and update implementation status sections +**CLI Commands Documentation Requirements:** +- **Comprehensive Coverage:** All CLI arguments, options, and flags must be documented with examples +- **Usage Examples:** Provide practical examples for common use cases and combinations +- **Configuration Details:** Document all configuration options and their effects +- **Error Handling:** Include troubleshooting information and common issues +- **Integration Notes:** Document how CLI integrates with web UI and other components +- **Version Tracking:** Keep version information and feature status up to date + This documentation requirement is mandatory and ensures the project remains maintainable and accessible to future developers and users. ### 2.3 Code Quality & Development Standards @@ -230,7 +240,8 @@ KaraokeMerge/ │ ├── matching.py # Song matching logic │ ├── report.py # Report generation │ ├── preferences.py # Priority preferences management -│ └── utils.py # Utility functions +│ ├── utils.py # Utility functions +│ └── commands.txt # Comprehensive CLI commands reference ├── web/ # Web UI for manual review │ ├── app.py # Flask web application │ └── templates/ diff --git a/cli/__pycache__/matching.cpython-313.pyc b/cli/__pycache__/matching.cpython-313.pyc index 288c5419db29c799c2aecbc40ffcc24143b4744b..314acf2bcba15ad508c84ebf5299fb07921cf848 100644 GIT binary patch delta 4155 zcmb^!S!^4}b(XtaQaoi*6sePxC|RN`SyC)TK4QnRBgam3Z&p?;)hZ>fWZKkHo~07o zZK@_+X8053mg>3fb~^~P_eQ^U>c-v|JwfgdFE*!U>WIWiC687-5}<)F zkwh8{k_I9`#{Fdb?DC+~9KAJ-KbHjo&vCFf{t^ z&GF@hf)7DMqFkz^{&`=tMt4dnb$&3Go;{_|zlPXb{JsX=9*?DC)A0nI<%Z(TMVd&_MEX1o3TO91^mvS_z_mAAbfUuxsrXV-39G4e zIQB#=k&MkG6()+y%WjH`*ZFxRP0>MGg`gTi4HEn#WBo_^$NGm3_e;}#<9){l`VI~B z(``ue71^C$Fq202o{DMHMFianZmMa$94r*!r)N`3fNk*}kx!g>d`okb*9A>U&KYje z3NWMLaR{^b#FVW8ryhE0ys@ZODT{%WX7h{WyiW=92cw#n9>)B~1S1GW*)xG2u?dIwvtI-v+-vM+ z;1VcH1W$1LjIHhgqHay7apj!u7>^~FlzvK61+T`DY@0n5Q&lBdCi6XL6Pn7&oMhBx=sAfONVlbtOk(_vCUf~rQ>_xOiXB9? z$yP}~(*^Bc1OIZkF(*44^|7a0gb-GEsP22XaDi%CQbpM|=0?8ioRn!fZwdHw^hd3d z4K4Y|xP81t<2#6E@sXo$LQkzXZT(4FJ$;<;O_QpS5C*>F*R4J zS@O}DgIMOrY`pebU=jjz#iDbXks}&D8NyFPcD2{-=RRa->cY!t{t8DQf(}YmEI~Eh zqoreNJeEwU%JjnGE=VxU6bk+kz053QX5pPq(YQkOa;Oc-^HAK1u@vtgsAVad)(oJUs zey@vf_FS*6->mIfukG2aJ-S|d^mi2-wZ|_FeeA8h8LZh1cCH6IH-r7_!TxJXMn16- zoP5E0Gf;DR^u=>4{*|*Ubfq#AXw8(i{=>dD7t*-Mufyd>Y8}5hP<|xhn9V)5z&0Uv z_>A;kW&aAl9#&V9=aqyzC?1Fos8+qQ z*NlnefRPhpQ3V5+5fpchx{CPo_<21 zS|X)JowOhI7}2c3sJq9;(nSytWD62MnTK069Mq{&26yZCpYX&2acnx+Cb zYnpyI{POVX;j7y=YIZ$0cGO+<5ewa2C?7PYp3zI5OeB-jXB1_TzJPii<|aLh8jYR$CXS3@0w)6FQDAJ1 z@6N5+1vRR0Or{g+T#8;qfo~%y?2+!6r>UhyldiCIc>C*IyJ)^a4R8D?W;}ZEsbiGjD0jiOb7u$sdx%L%mcaCF->2AR+t{|wmzHl;v|F22;;Y?P`K!`Z z`;`Oh+xKP(;I17uy3FwtWjEqh;(yz8*{`T2LtIfOxbUxa_RfdlwoyeeTm delta 2978 zcmb_eTWlOx89rxjdtYDH_S);quDy=!N#a|wc9O=qIK*k3)@hQ-My|b$uj}=;&g}Ng z8tPJVsnV!GD^wi?QHm-*6^94p$}gxwBo-hA2_##f03*sv9}p5!7ZO2)gv9@!^{yRA zd19pb=FERP|M~y#oSDCxKS=r?`h0Ezmv#27`K7-1{I&GM_u4ZDYe@?+Tp?n(`y^Bo z!fH}VGfDUyWJ)C@LJSA?Vw&L=Qm^3wi5G4k+My7Hz^GWvSI$ow6mS!ZL4^~MZ(zOMp zgGzD2d+MtE9ff+5sojK(d-<|f-CVXMB8IaMs*6{IjBiU_{DBsxZvJ;|oG&}B4m(*D znAmbEnPW9DVzmf$2q9FIor;f*y*M#=X>j=Y!4uC9*=m-h&73aTij`cL6W$h*g8$r^ zaWufdS|$9j>&9Bh%^b9jzgy8%g)wbyDw|E3v$isup2@LBez#(`)&vR`<)2s7(>Cs@ z{4Ndik1B_$zLu|a$h2kcadm`hBAEu>6s)Ti_Jinj0%wu|B9RCS^B01L=)3&u!DHa` zi{PiUX9$f7o;W&%fD6(cOawWNf?@W~2pt5;b9AGK(7 z{ZQ4(e)ms#=+l7Ap%5xAL6#U0RRgAmg>?tyUPiaQN?XD>}xTrH3> z?m8kJ5%eu`D|y^1i3z!0(s7J%)VUCb_|XQpyV)`mhXsICepTVu&7D`RdeZ0{?{Y;NMq zNoJ)prtW6P&;^;p@Hnw$IF)TRol9P^7&e7@Ne`enx?aKey#RVy;q*g-v0eb%J)N|2 z6EIWCVrl-Dj%Yb@&X$v}PspFuM!A3Y zg8b`U&+_ZLZv}MH-j^RB<)P)pjk3KP&b_Qfe z&m+T)Y#d(LO9+<%N?Qm8ll-%;qpb}T#Q5oYe4VUZ{B7r{&CXNzUcFzlzVw^U^9=VF zo908^xsw<+{U<1qF0pzPV{u?S0S~)uF2k-&UPw;lma<89kss@6x^@e+#iqQ5j@TJnwV=VdLO+ry?Lxr)R%ndqN#H+w;xF-H zB5gv3@Btv~4TKU+YCf8znsE}WiK76Cuq7XBaJBEMG-<`s|H@txfA zmsSGHr{BN&h`?(;#EsauU&_}+)m_W8E3s91)mU}jIl9^QOrC)3M~n9^-jCk5?su$T z-iW`rF?M-lVtQjXwK0*}9Gl;ar#FVuo5x;$gtqxJv`g(=j;$yw#%gqB^p1ZsdLU1_ z__e;{DroYP{AYbVK9MJ;s0Y~xoc5om4czE|MlYnjjJcPVVmk+}WM&r^l1JJ1K>;fv z)+PR{{sRa9Q8TX4roR!y$N5I$3_K*1HvF!p{>>NiGK~IdRe<&PoP(6CQ|F*pUiVPI Fe*+RxLPh`p diff --git a/cli/commands.txt b/cli/commands.txt new file mode 100644 index 0000000..b534e44 --- /dev/null +++ b/cli/commands.txt @@ -0,0 +1,262 @@ +# Karaoke Song Library Cleanup Tool - CLI Commands Reference + +## Overview +The CLI tool analyzes karaoke song collections, identifies duplicates, and generates skip lists for future imports. It supports multiple file formats (MP3, CDG, MP4) with configurable priority systems. + +## Basic Usage + +### Standard Analysis +```bash +python cli/main.py +``` +Runs the tool with default settings: +- Input: `data/allSongs.json` +- Config: `config/config.json` +- Output: `data/skipSongs.json` +- Verbose: Disabled +- Reports: Not saved + +### Verbose Output +```bash +python cli/main.py --verbose +# or +python cli/main.py -v +``` +Enables detailed output showing: +- Individual song processing +- Duplicate detection details +- File type analysis +- Channel priority decisions + +### Dry Run Mode +```bash +python cli/main.py --dry-run +``` +Analyzes songs without generating the skip list file. Useful for: +- Testing configuration changes +- Previewing results before committing +- Validating input data + +## Configuration Options + +### Custom Configuration File +```bash +python cli/main.py --config path/to/custom_config.json +``` +Uses a custom configuration file instead of the default `config/config.json`. + +### Show Current Configuration +```bash +python cli/main.py --show-config +``` +Displays the current configuration settings and exits. Useful for: +- Verifying configuration values +- Debugging configuration issues +- Understanding current settings + +## Input/Output Options + +### Custom Input File +```bash +python cli/main.py --input path/to/songs.json +``` +Specifies a custom input file instead of the default `data/allSongs.json`. + +### Custom Output Directory +```bash +python cli/main.py --output-dir ./custom_output +``` +Saves output files to a custom directory instead of the default `data/` folder. + +## Report Generation + +### Save Detailed Reports +```bash +python cli/main.py --save-reports +``` +Generates comprehensive analysis reports in the output directory: +- `enhanced_summary_report.txt` - Comprehensive analysis +- `channel_optimization_report.txt` - Priority optimization suggestions +- `duplicate_pattern_report.txt` - Duplicate pattern analysis +- `actionable_insights_report.txt` - Recommendations and insights +- `detailed_duplicate_analysis.txt` - Specific songs and their duplicates +- `analysis_data.json` - Raw analysis data for further processing +- `skip_songs_detailed.json` - Full skip list with metadata + +## Combined Examples + +### Full Analysis with Reports +```bash +python cli/main.py --verbose --save-reports +``` +Runs complete analysis with: +- Verbose output for detailed processing information +- Comprehensive report generation +- Skip list creation + +### Custom Configuration with Dry Run +```bash +python cli/main.py --config custom_config.json --dry-run --verbose +``` +Tests a custom configuration without generating files: +- Uses custom configuration +- Shows detailed processing +- No output files created + +### Custom Input/Output with Reports +```bash +python cli/main.py --input /path/to/songs.json --output-dir ./reports --save-reports +``` +Processes custom input and saves all outputs to reports directory: +- Custom input file +- Custom output location +- All report files generated + +### Minimal Output +```bash +python cli/main.py --output-dir ./minimal +``` +Runs with minimal output: +- No verbose logging +- No detailed reports +- Only generates skip list + +## Configuration File Structure + +The default configuration file (`config/config.json`) contains: + +```json +{ + "channel_priorities": [ + "Sing King Karaoke", + "KaraFun Karaoke", + "Stingray Karaoke" + ], + "matching": { + "fuzzy_matching": false, + "fuzzy_threshold": 0.85, + "case_sensitive": false + }, + "output": { + "verbose": false, + "include_reasons": true, + "max_duplicates_per_song": 10 + }, + "file_types": { + "supported_extensions": [".mp3", ".cdg", ".mp4"], + "mp4_extensions": [".mp4"] + } +} +``` + +### Configuration Options Explained + +#### Channel Priorities +- **channel_priorities**: Array of folder names for MP4 files +- Order determines priority (first = highest priority) +- Files without matching folders are marked for manual review + +#### Matching Settings +- **fuzzy_matching**: Enable/disable fuzzy string matching +- **fuzzy_threshold**: Similarity threshold (0.0-1.0) for fuzzy matching +- **case_sensitive**: Case-sensitive artist/title comparison + +#### Output Settings +- **verbose**: Enable detailed output +- **include_reasons**: Include reason field in skip list +- **max_duplicates_per_song**: Maximum duplicates to process per song + +#### File Type Settings +- **supported_extensions**: All supported file extensions +- **mp4_extensions**: Extensions treated as MP4 files + +## Input File Format + +The tool expects a JSON array of song objects: + +```json +[ + { + "artist": "Artist Name", + "title": "Song Title", + "path": "path/to/file.mp3" + } +] +``` + +Optional fields for MP4 files: +- `channel`: Channel/folder information +- ID3 tag information (artist, title, etc.) + +## Output Files + +### Primary Output +- **skipSongs.json**: List of file paths to skip in future imports +- Format: `[{"path": "file/path.mp3", "reason": "duplicate"}]` + +### Report Files (with --save-reports) +- **enhanced_summary_report.txt**: Overall analysis and statistics +- **channel_optimization_report.txt**: Channel priority suggestions +- **duplicate_pattern_report.txt**: Duplicate detection patterns +- **actionable_insights_report.txt**: Recommendations for collection management +- **detailed_duplicate_analysis.txt**: Specific duplicate groups +- **analysis_data.json**: Raw data for further processing +- **skip_songs_detailed.json**: Complete skip list with metadata + +## File Type Priority System + +The tool processes files in this priority order: + +1. **MP4 files** (with channel priority sorting) +2. **CDG/MP3 pairs** (treated as single units) +3. **Standalone MP3** files +4. **Standalone CDG** files + +## Error Handling + +The tool provides clear error messages for: +- Missing input files +- Invalid JSON format +- Configuration errors +- File permission issues +- Processing errors + +## Performance Notes + +- Successfully tested with 37,000+ songs +- Processes large datasets efficiently +- Shows progress indicators for long operations +- Memory-efficient processing + +## Integration with Web UI + +The CLI tool integrates with the web UI: +- Web UI can load CLI-generated data +- Priority preferences from web UI are used by CLI +- Shared configuration and data files +- Consistent processing logic + +## Troubleshooting + +### Common Issues +1. **File not found**: Check input file path and permissions +2. **JSON errors**: Validate input file format +3. **Configuration errors**: Use --show-config to verify settings +4. **Permission errors**: Check output directory permissions + +### Debug Mode +```bash +python cli/main.py --verbose --dry-run --show-config +``` +Complete debugging setup: +- Shows configuration +- Verbose processing +- No file changes + +## Version Information + +This commands reference is for Karaoke Song Library Cleanup Tool v2.0 +- CLI: Fully functional with comprehensive options +- Web UI: Interactive priority management +- Priority System: Drag-and-drop with persistence +- Reports: Enhanced analysis with actionable insights \ No newline at end of file diff --git a/cli/main.py b/cli/main.py index 491858c..c3c2933 100644 --- a/cli/main.py +++ b/cli/main.py @@ -123,6 +123,7 @@ def main(): songs = load_songs(args.input) # Initialize components + data_dir = args.output_dir matcher = SongMatcher(config, data_dir) reporter = ReportGenerator(config)