KaraokeMerge/cli/commands.txt

# Karaoke Song Library Cleanup Tool - CLI Commands Reference (v2.0)

## Overview
The CLI tool analyzes karaoke song collections, identifies duplicates, validates playlists, and generates skip lists for future imports. It supports multiple file formats (MP3, CDG, MP4) with configurable priority systems.

## Quick Start Commands

### Basic Analysis (Most Common)
```bash
cd cli
python3 main.py
```
Runs the tool with default settings:
- Input: `data/allSongs.json`
- Config: `config/config.json`
- Output: `data/skipSongs.json`
- Reports: **Automatically generated**

### Process Everything (Recommended)
```bash
cd cli
python3 main.py --process-all
```
Complete processing including:
- Duplicate analysis and skip list generation
- Favorites processing with priority logic (MP4 over MP3)
- History processing with priority logic
- Comprehensive report generation

## Main CLI Commands (main.py)

### Basic Analysis Commands

#### Standard Analysis
```bash
python3 main.py
```
Runs the tool with default settings and generates all reports automatically.

#### Verbose Output
```bash
python3 main.py --verbose
# or
python3 main.py -v
```
Enables detailed output showing individual song processing and decisions.

#### Dry Run Mode
```bash
python3 main.py --dry-run
```
Analyzes songs without generating the skip list file. Useful for testing and previewing results.

### Configuration Commands

#### Custom Configuration File
```bash
python3 main.py --config path/to/custom_config.json
```
Uses a custom configuration file instead of the default `config/config.json`.

#### Show Current Configuration
```bash
python3 main.py --show-config
```
Displays the current configuration settings and exits.

### Input/Output Commands

#### Custom Input File
```bash
python3 main.py --input path/to/songs.json
```
Specifies a custom input file instead of the default `data/allSongs.json`.

#### Custom Output Directory
```bash
python3 main.py --output-dir ./custom_output
```
Saves output files to a custom directory instead of the default `data/` folder.

### Processing Commands

#### Process Favorites Only
```bash
python3 main.py --process-favorites
```
Processes favorites with priority-based logic to select best versions (MP4 over MP3).

#### Process History Only
```bash
python3 main.py --process-history
```
Processes history with priority-based logic to select best versions (MP4 over MP3).

#### Process Everything
```bash
python3 main.py --process-all
```
Processes everything: duplicates, generates reports, AND updates favorites/history with priority logic.

#### Merge History Objects
```bash
python3 main.py --merge-history
```
Merges history objects that match on artist, title, and path, summing their count properties.

### Report Generation

#### Save Detailed Reports (Legacy)
```bash
python3 main.py --save-reports
```
**Note**: Reports are now automatically generated every time you run the CLI tool. This flag is kept for backward compatibility.

Generated reports include:
- `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` - **Web UI data (always generated)**

## Playlist Validator Commands (playlist_validator.py)

### Basic Playlist Validation

#### Validate All Playlists
```bash
python3 playlist_validator.py
```
Validates all playlists in `data/songLists.json` against the song library.

#### Validate Specific Playlist
```bash
python3 playlist_validator.py --playlist-index 0
```
Validates a specific playlist by index (0-based).

### Playlist Validator Options

#### Custom Configuration
```bash
python3 playlist_validator.py --config path/to/custom_config.json
```
Uses a custom configuration file.

#### Custom Data Directory
```bash
python3 playlist_validator.py --data-dir path/to/data
```
Uses a custom data directory.

#### Apply Changes (Disable Dry Run)
```bash
python3 playlist_validator.py --apply
```
Applies changes to playlists instead of just previewing them.

#### Output Results to File
```bash
python3 playlist_validator.py --output results.json
```
Saves validation results to a JSON file.

## Comprehensive Examples

### Complete Workflow Examples

#### 1. Full Analysis with Everything
```bash
cd cli
python3 main.py --process-all --verbose
```
Complete processing with detailed output:
- Duplicate analysis and skip list generation
- Favorites and history processing with priority logic
- Comprehensive report generation
- Verbose output for detailed processing information

#### 2. Preview Changes Before Applying
```bash
cd cli
python3 main.py --process-all --dry-run --verbose
```
Preview all changes without saving:
- Shows what would be processed
- No files are modified
- Useful for testing configuration changes

#### 3. Custom Configuration Testing
```bash
cd cli
python3 main.py --config custom_config.json --dry-run --verbose
```
Test a custom configuration:
- Uses custom configuration file
- Shows detailed processing
- No output files created

#### 4. Process Only Favorites and History
```bash
cd cli
python3 main.py --process-favorites --process-history
```
Process only favorites and history files:
- Updates favorites with best versions (MP4 over MP3)
- Updates history with best versions
- No duplicate analysis performed

#### 5. Merge History Objects
```bash
cd cli
python3 main.py --merge-history --dry-run
```
Preview history merging:
- Shows which history objects would be merged
- No files are modified

#### 6. Apply History Merging
```bash
cd cli
python3 main.py --merge-history
```
Actually merge history objects:
- Combines duplicate history entries
- Sums count properties
- Saves updated history file

### Playlist Validation Examples

#### 1. Validate All Playlists
```bash
cd cli
python3 playlist_validator.py
```
Validates all playlists and shows summary:
- Total playlists and songs
- Exact matches found
- Missing songs count
- Fuzzy matches (if available)

#### 2. Validate Specific Playlist
```bash
cd cli
python3 playlist_validator.py --playlist-index 5
```
Validates playlist at index 5:
- Shows detailed results for that specific playlist
- Lists exact matches and missing songs

#### 3. Save Validation Results
```bash
cd cli
python3 playlist_validator.py --output validation_results.json
```
Saves detailed validation results to JSON file for further analysis.

#### 4. Apply Playlist Corrections
```bash
cd cli
python3 playlist_validator.py --apply
```
Applies corrections to playlists (use with caution).

### Advanced Examples

#### 1. Custom Input/Output with Full Processing
```bash
cd cli
python3 main.py --input /path/to/songs.json --output-dir ./reports --process-all --verbose
```
Processes custom input and saves all outputs to reports directory:
- Custom input file
- Custom output location
- Full processing including favorites/history
- Verbose output

#### 2. Configuration Testing Workflow
```bash
cd cli
# Show current configuration
python3 main.py --show-config

# Test with dry run
python3 main.py --dry-run --verbose

# Test with custom config
python3 main.py --config test_config.json --dry-run --verbose
```

#### 3. Playlist Analysis Workflow
```bash
cd cli
# Validate all playlists
python3 playlist_validator.py

# Validate specific playlist
python3 playlist_validator.py --playlist-index 0

# Save detailed results
python3 playlist_validator.py --output playlist_analysis.json
```

#### 4. Complete System Analysis
```bash
cd cli
# Process everything
python3 main.py --process-all --verbose

# Validate playlists
python3 playlist_validator.py

# Show configuration
python3 main.py --show-config
```

## Command Line Options Reference

### Main CLI (main.py) Options

| Option | Description | Default |
|--------|-------------|---------|
| `--config` | Configuration file path | `../config/config.json` |
| `--input` | Input songs file path | `../data/allSongs.json` |
| `--output-dir` | Output directory | `../data` |
| `--verbose, -v` | Enable verbose output | `False` |
| `--dry-run` | Analyze without generating files | `False` |
| `--save-reports` | Save detailed reports | `True` (always enabled) |
| `--show-config` | Show configuration and exit | `False` |
| `--process-favorites` | Process favorites with priority logic | `False` |
| `--process-history` | Process history with priority logic | `False` |
| `--process-all` | Process everything | `False` |
| `--merge-history` | Merge history objects | `False` |

### Playlist Validator (playlist_validator.py) Options

| Option | Description | Default |
|--------|-------------|---------|
| `--config` | Configuration file path | `../config/config.json` |
| `--data-dir` | Data directory path | `../data` |
| `--dry-run` | Dry run mode | `True` |
| `--apply` | Apply changes (disable dry run) | `False` |
| `--playlist-index` | Validate specific playlist by index | `None` |
| `--output` | Output results to JSON file | `None` |

## File Structure Requirements

### Required Files
- `data/allSongs.json` - Main song library
- `config/config.json` - Configuration settings

### Optional Files
- `data/favorites.json` - Favorites list (for processing)
- `data/history.json` - History list (for processing)
- `data/songLists.json` - Playlists (for validation)

### Generated Files
- `data/skipSongs.json` - Skip list for future imports
- `data/reports/` - Directory containing all analysis reports
- `data/preferences/` - Directory containing priority preferences

## 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"]
  }
}
```

## Input File Formats

### Song Library Format (allSongs.json)
```json
[
  {
    "artist": "Artist Name",
    "title": "Song Title", 
    "path": "path/to/file.mp3"
  }
]
```

### Playlist Format (songLists.json)
```json
[
  {
    "title": "Playlist Name",
    "songs": [
      {
        "position": 1,
        "artist": "Artist Name",
        "title": "Song Title"
      }
    ]
  }
]
```

### Favorites Format (favorites.json)
```json
[
  {
    "artist": "Artist Name",
    "title": "Song Title",
    "path": "path/to/file.mp3",
    "favorite": true
  }
]
```

### History Format (history.json)
```json
[
  {
    "artist": "Artist Name",
    "title": "Song Title",
    "path": "path/to/file.mp3",
    "count": 5
  }
]
```

## Output Files

### Primary Output
- **skipSongs.json**: List of file paths to skip in future imports
- Format: `[{"path": "file/path.mp3", "reason": "duplicate"}]`

### Report Files (Automatically Generated)
- **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 49,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
cd cli
python3 main.py --verbose --dry-run --show-config
```
Complete debugging setup:
- Shows configuration
- Verbose processing
- No file changes

### Playlist Validator Debug
```bash
cd cli
python3 playlist_validator.py --dry-run --output debug_results.json
```
Debug playlist validation:
- Dry run mode
- Save results to file
- No playlist modifications

## 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
- Playlist Validator: Complete playlist analysis and validation