diff --git a/completions/README.md b/completions/README.md index 13569c5..287332a 100644 --- a/completions/README.md +++ b/completions/README.md @@ -43,7 +43,7 @@ The completion system provides intelligent tab completion for command-line flags - `--help`, `-h` - Show help message - `--dry-run` - Preview backup without executing -- `--no-upload` - Skip B2 upload (local backup only) +- `--no-upload` - Skip B2 upload (local backup only) - `--verbose` - Enable verbose logging ### backup-plex.sh @@ -187,7 +187,7 @@ backup-immich.sh -- # Relative path ./backup-immich.sh -- -# Absolute path +# Absolute path /home/acedanger/shell/immich/backup-immich.sh -- ``` @@ -276,9 +276,9 @@ _script_name_completion() { COMPREPLY=() cur="${COMP_WORDS[COMP_CWORD]}" prev="${COMP_WORDS[COMP_CWORD-1]}" - + opts="--option1 --option2 --option3" - + # Handle special cases case "${prev}" in --special-option) @@ -286,7 +286,7 @@ _script_name_completion() { return 0 ;; esac - + # Standard flag completion if [[ ${cur} == -* ]]; then COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) diff --git a/completions/plex-completion-implementation.md b/completions/plex-completion-implementation.md index 38c19df..a6c4ae8 100644 --- a/completions/plex-completion-implementation.md +++ b/completions/plex-completion-implementation.md @@ -131,7 +131,7 @@ For commands that accept boolean flags: $ scan-plex-libraries.sh refresh 29 true false -# Analyze with deep flag +# Analyze with deep flag $ scan-plex-libraries.sh analyze 29 true false ``` diff --git a/completions/plex-scripts-completion.bash b/completions/plex-scripts-completion.bash index 20d80fd..27670d5 100755 --- a/completions/plex-scripts-completion.bash +++ b/completions/plex-scripts-completion.bash @@ -2,7 +2,7 @@ # Bash completion for Plex-related scripts # Author: Peter Wood -# +# # This file provides intelligent tab completion for: # - plex.sh (main Plex management script) # - scan-plex-libraries.sh (library scanner script) @@ -16,16 +16,16 @@ _plex_sh_completion() { local cur="${COMP_WORDS[COMP_CWORD]}" local prev="${COMP_WORDS[COMP_CWORD-1]}" - + # Available commands for plex.sh local commands="start stop restart status scan repair nuclear help" - + # If we're completing the first argument (command) if [[ ${COMP_CWORD} -eq 1 ]]; then COMPREPLY=($(compgen -W "$commands" -- "$cur")) return 0 fi - + # If previous word was 'scan', complete with scanner options if [[ "$prev" == "scan" ]]; then local scanner_commands="list scan refresh analyze generate tree interactive" @@ -33,7 +33,7 @@ _plex_sh_completion() { COMPREPLY=($(compgen -W "$scanner_commands $scanner_options" -- "$cur")) return 0 fi - + # For other commands, no additional completion needed return 0 } @@ -42,11 +42,11 @@ _plex_sh_completion() { _scan_plex_libraries_completion() { local cur="${COMP_WORDS[COMP_CWORD]}" local prev="${COMP_WORDS[COMP_CWORD-1]}" - + # Available commands for scan-plex-libraries.sh local commands="list scan refresh analyze generate tree interactive" local options="-v --verbose -h --help" - + # If we're completing the first argument if [[ ${COMP_CWORD} -eq 1 ]]; then # If it starts with -, show options @@ -57,7 +57,7 @@ _scan_plex_libraries_completion() { fi return 0 fi - + # Handle specific command completions case "${COMP_WORDS[1]}" in refresh) @@ -79,19 +79,19 @@ _scan_plex_libraries_completion() { # Could potentially call the script to get section IDs but that's expensive ;; esac - + return 0 } # Completion function for generic plex aliases that might pass through to plex.sh _plex_alias_completion() { local cur="${COMP_WORDS[COMP_CWORD]}" - + # For plex-scan alias, complete with scanner commands if [[ "${COMP_WORDS[0]}" == *"plex-scan"* ]]; then local scanner_commands="list scan refresh analyze generate tree interactive" local scanner_options="-v --verbose -h --help" - + if [[ ${COMP_CWORD} -eq 1 ]]; then if [[ "$cur" == -* ]]; then COMPREPLY=($(compgen -W "$scanner_options" -- "$cur")) @@ -105,13 +105,13 @@ _plex_alias_completion() { fi return 0 fi - + # For plex-scanner alias, use the full scanner completion if [[ "${COMP_WORDS[0]}" == *"plex-scanner"* ]]; then _scan_plex_libraries_completion return 0 fi - + # For other plex aliases, just complete with main plex.sh commands local commands="start stop restart status scan repair nuclear help" COMPREPLY=($(compgen -W "$commands" -- "$cur")) @@ -123,10 +123,10 @@ _plex_alias_completion() { _plex_scanner_with_sections() { local cur="${COMP_WORDS[COMP_CWORD]}" local prev="${COMP_WORDS[COMP_CWORD-1]}" - + # First try the basic completion _scan_plex_libraries_completion - + # If we didn't get any completions and we're looking for a section ID if [[ ${#COMPREPLY[@]} -eq 0 ]]; then case "${COMP_WORDS[1]}" in @@ -136,14 +136,14 @@ _plex_scanner_with_sections() { # Attempt to get section IDs from the scanner local script_dir="$(dirname "${COMP_WORDS[0]}")" local scanner_script="" - + # Try to find the scanner script if [[ -f "$script_dir/scan-plex-libraries.sh" ]]; then scanner_script="$script_dir/scan-plex-libraries.sh" elif [[ -f "/home/acedanger/shell/plex/scan-plex-libraries.sh" ]]; then scanner_script="/home/acedanger/shell/plex/scan-plex-libraries.sh" fi - + if [[ -n "$scanner_script" ]]; then # Attempt to get section IDs (with timeout to avoid hanging) local section_ids @@ -155,7 +155,7 @@ _plex_scanner_with_sections() { ;; esac fi - + return 0 } @@ -199,7 +199,7 @@ _plex_list_sections() { _plex_extended_completion() { local cur="${COMP_WORDS[COMP_CWORD]}" local cmd="${COMP_WORDS[0]}" - + # This function can be extended for future plex-related commands case "$cmd" in *plex-backup*) @@ -209,7 +209,7 @@ _plex_extended_completion() { # If restore scripts get their own completion, handle here ;; esac - + return 0 } diff --git a/plex/plex-management.md b/plex/plex-management.md index 964ec9c..9400038 100644 --- a/plex/plex-management.md +++ b/plex/plex-management.md @@ -11,15 +11,16 @@ This document provides comprehensive documentation for the modern `plex.sh` scri The enhanced `plex.sh` script is a modern Plex service management tool that performs the following advanced tasks: 1. **Smart Service Management**: Intelligent start/stop/restart operations with dependency checking -2. **Enhanced Status Display**: Detailed service status with health indicators and port monitoring -3. **Safety Validation**: Pre-operation checks and post-operation verification -4. **Progress Indicators**: Visual feedback for all operations with timing information -5. **Comprehensive Logging**: Detailed logging with color-coded output and timestamps -6. **Configuration Validation**: Checks for common configuration issues -7. **Network Monitoring**: Port availability and network configuration validation -8. **Process Management**: Advanced process monitoring and cleanup capabilities -9. **Recovery Operations**: Automatic recovery from common service issues -10. **Performance Monitoring**: Service health and resource usage tracking +2. **Library Scanner Integration**: Integrated access to comprehensive library scanning operations +3. **Enhanced Status Display**: Detailed service status with health indicators and port monitoring +4. **Safety Validation**: Pre-operation checks and post-operation verification +5. **Progress Indicators**: Visual feedback for all operations with timing information +6. **Comprehensive Logging**: Detailed logging with color-coded output and timestamps +7. **Configuration Validation**: Checks for common configuration issues +8. **Network Monitoring**: Port availability and network configuration validation +9. **Process Management**: Advanced process monitoring and cleanup capabilities +10. **Recovery Operations**: Automatic recovery from common service issues +11. **Performance Monitoring**: Service health and resource usage tracking ## Related Scripts in the Plex Ecosystem @@ -28,6 +29,7 @@ This script is part of a comprehensive Plex management suite: ### Core Management Scripts - **`plex.sh`** (this script) - Service management and control +- **`scan-plex-libraries.sh`** ⭐ **NEW** - Comprehensive library scanning and metadata management - **`backup-plex.sh`** - Database backup with integrity checking and auto-repair - **`restore-plex.sh`** - Safe database restoration with validation @@ -49,6 +51,266 @@ This script is part of a comprehensive Plex management suite: - **`plex-recent-additions.sh`** - Recent media additions reporting and statistics +## Library Scanner Integration ⭐ **NEW** + +### Overview + +The `plex.sh` script now includes integrated access to comprehensive library scanning functionality through the new `scan-plex-libraries.sh` script. This integration provides seamless access to all Plex Media Scanner operations directly from the main management interface. + +### Library Scanner Features + +The integrated library scanner provides: + +- **Library Management**: List all Plex library sections with IDs and names +- **Media Scanning**: Scan for new media files (individual libraries or all at once) +- **Metadata Refresh**: Refresh library metadata with force options for complete rebuilds +- **Deep Analysis**: Comprehensive media analysis for codec information and metadata +- **Thumbnail Generation**: Generate preview thumbnails and fanart images +- **Library Structure**: Display hierarchical library structure and organization +- **Interactive Mode**: User-friendly menu system for easy library management +- **Batch Operations**: Perform operations on all libraries or specific selections +- **Error Handling**: Comprehensive validation and error reporting +- **Service Integration**: Automatic Plex service status validation before operations + +### Scanner Integration Commands + +The library scanner is accessible through the main `plex.sh` script: + +```bash +# Launch interactive scanner interface +./plex.sh scan + +# Pass commands directly to scanner +./plex.sh scan list # List all libraries +./plex.sh scan scan # Scan all libraries for new media +./plex.sh scan scan 29 # Scan specific library (ID 29) +./plex.sh scan refresh 29 true # Force refresh specific library +./plex.sh scan analyze 29 true # Deep analyze specific library +./plex.sh scan generate 29 # Generate thumbnails for library +./plex.sh scan tree 29 # Show library structure +``` + +### Direct Scanner Access + +The scanner can also be accessed directly: + +```bash +# Direct script execution +./scan-plex-libraries.sh interactive # Interactive mode +./scan-plex-libraries.sh list # List libraries +./scan-plex-libraries.sh scan # Scan all libraries +./scan-plex-libraries.sh -v scan 29 # Verbose scan of specific library + +# Via aliases (if shell configuration is loaded) +plex-scan # Launch via plex.sh integration +plex-scanner list # Direct scanner access +plex-scanner scan 29 # Direct scan of specific library +``` + +### Scanner Command Reference + +#### Core Scanner Commands + +- **`list`** - Display all available library sections with IDs and names +- **`scan [section_id]`** - Scan for new media files (all libraries if no ID specified) +- **`refresh [section_id] [force]`** - Refresh metadata (set force=true for complete refresh) +- **`analyze [section_id] [deep]`** - Analyze media files (set deep=true for comprehensive analysis) +- **`generate [section_id]`** - Generate thumbnails and fanart images +- **`tree `** - Display hierarchical library structure (requires section ID) +- **`interactive`** - Launch interactive menu system + +#### Scanner Options + +- **`-v, --verbose`** - Enable verbose output for detailed operation information +- **`-h, --help`** - Display comprehensive help and usage information + +#### Example Scanner Operations + +```bash +# List all available libraries with their section IDs +$ ./plex.sh scan list +Available Library Sections: +========================= + 29: Movies + 30: TV Shows + 31: Music + +# Scan Movies library for new content +$ ./plex.sh scan scan 29 +[>] Scanning library section 29 for new media... +[✓] Library section 29 scan completed + +# Force refresh all libraries (complete metadata rebuild) +$ ./plex.sh scan refresh "" true +[~] Refreshing metadata for all libraries... +[i] Refreshing section 29... +[✓] Section 29 refreshed successfully +[i] Refreshing section 30... +[✓] Section 30 refreshed successfully +[✓] All libraries refreshed successfully + +# Deep analyze TV Shows library +$ ./plex.sh scan analyze 30 true +[?] Analyzing media in library section 30... +[✓] Library section 30 analysis completed + +# Generate thumbnails for Movies library +$ ./plex.sh scan generate 29 +[*] Generating thumbnails for library section 29... +[✓] Thumbnails generated for library section 29 +``` + +### Interactive Scanner Mode + +The interactive mode provides a user-friendly menu system: + +```bash +$ ./plex.sh scan +🎬 Plex Library Scanner - Interactive Mode +Select an operation to perform: + +Available Operations: +1) List all libraries +2) Scan libraries for new media +3) Refresh library metadata +4) Analyze library media +5) Generate thumbnails +6) Show library tree +q) Quit + +Choose an option [1-6,q]: 2 + +Scan Options: +1) Scan all libraries +2) Scan specific library +Choose [1-2]: 1 + +[>] Scanning all libraries for new media... +[✓] All libraries scanned successfully +``` + +### Scanner Error Handling and Validation + +The library scanner includes comprehensive error handling: + +- **Service Validation**: Automatically checks if Plex Media Server is running +- **Scanner Detection**: Locates Plex Media Scanner binary across different installation paths +- **Section ID Validation**: Verifies library section IDs exist before operations +- **Operation Verification**: Confirms successful completion of all scanner operations +- **Graceful Failure**: Provides helpful error messages and recovery suggestions + +### Scanner Logging and Monitoring + +All scanner operations are logged: + +- **Operation Logs**: Detailed logs written to `/home/acedanger/shell/logs/plex-scanner.log` +- **Timestamp Tracking**: All operations include precise timestamps +- **Verbose Mode**: Enhanced debugging information available with `-v` flag +- **Status Reporting**: Real-time status updates during long-running operations + +### Scanner Performance Considerations + +For optimal performance: + +- **Large Libraries**: Scanner operations may take considerable time for large media collections +- **Deep Analysis**: Deep analysis is resource-intensive, use selectively +- **Concurrent Operations**: Avoid running multiple scanner operations simultaneously +- **System Resources**: Scanner operations can be CPU and I/O intensive during execution + +### Scanner Best Practices + +Recommended usage patterns: + +1. **Regular Scanning**: Set up regular scans for libraries with frequent media additions +2. **Selective Operations**: Use specific section IDs for targeted operations when possible +3. **Monitor Progress**: Use verbose mode to understand operation progress and impact +4. **Service Health**: Ensure Plex service is healthy before performing scanner operations +5. **Batch Operations**: For multiple libraries, consider using "scan all" for efficiency + +### Scanner Troubleshooting + +Common issues and solutions: + +1. **"Plex Media Server is not running"** + - Start Plex: `./plex.sh start` + - Verify status: `./plex.sh status` + +2. **"Plex Media Scanner binary not found"** + - Verify Plex installation is complete + - Check if binary exists in standard locations + - Ensure proper system PATH configuration + +3. **"Section ID not found"** + - Use `./plex.sh scan list` to see valid section IDs + - Verify the library hasn't been deleted or renamed + +4. **Scanner operations timeout or fail** + - Check system resources (CPU, memory, disk I/O) + - Verify media files are accessible and not corrupted + - Review scanner logs for detailed error information + +### Scanner Bash Completion ⭐ **NEW** + +The library scanner includes comprehensive bash completion support: + +#### Tab Completion Features + +- **Command Completion**: Tab completion for all scanner commands and options +- **Context-Aware**: Different completions based on command context +- **Boolean Flags**: Smart completion for `true`/`false` values where applicable +- **Alias Support**: Completion works with all plex-related aliases + +#### Example Tab Completion Usage + +```bash +# Main plex.sh command completion +$ ./plex.sh +start stop restart status scan repair nuclear help + +# Scanner sub-command completion +$ ./plex.sh scan +list scan refresh analyze generate tree interactive -v --verbose -h --help + +# Boolean flag completion for refresh and analyze +$ ./plex.sh scan refresh 29 +true false + +$ ./plex.sh scan analyze 29 +true false + +# Direct scanner completion +$ ./scan-plex-libraries.sh +list scan refresh analyze generate tree interactive + +# Alias completion +$ plex-scan +list scan refresh analyze generate tree interactive + +$ plex-scanner +list scan refresh analyze generate tree interactive +``` + +#### Completion Installation + +Bash completion is automatically installed by the setup scripts: + +- **Automatic Setup**: Installed by `bootstrap.sh` and `setup.sh` +- **Shell Integration**: Sourced in `.zshrc` for immediate availability +- **Alias Support**: Works with all plex-related aliases (`plex`, `plex-scan`, `plex-scanner`, etc.) + +#### Manual Completion Setup + +If needed, completion can be enabled manually: + +```bash +# Enable bash completion in zsh +autoload -U +X bashcompinit && bashcompinit +autoload -U compinit && compinit -u + +# Source the completion script +source /home/acedanger/shell/completions/plex-scripts-completion.bash +``` + ## Enhanced Features ### Smart Terminal Detection and Color Output @@ -139,6 +401,9 @@ Shows: # Display comprehensive status ./plex.sh status + +# Launch library scanner +./plex.sh scan ``` ### Available Commands @@ -148,12 +413,23 @@ The script supports the following commands: ```bash # Basic service operations ./plex.sh start # Start Plex Media Server -./plex.sh stop # Stop Plex Media Server +./plex.sh stop # Stop Plex Media Server ./plex.sh restart # Restart Plex Media Server (also accepts 'reload') ./plex.sh status # Show detailed service status (also accepts 'info') +./plex.sh scan # Launch library scanner (NEW) ./plex.sh logs # Display recent Plex Media Server logs ./plex.sh help # Show help message (also accepts '--help' or '-h') +# Library scanner operations (NEW) +./plex.sh scan # Interactive scanner mode +./plex.sh scan list # List all library sections +./plex.sh scan scan # Scan all libraries for new media +./plex.sh scan scan 29 # Scan specific library (ID 29) +./plex.sh scan refresh 29 true # Force refresh specific library +./plex.sh scan analyze 29 true # Deep analyze specific library +./plex.sh scan generate 29 # Generate thumbnails for library +./plex.sh scan tree 29 # Show library structure + # Logs command with options ./plex.sh logs # Display last 20 lines of Plex logs ./plex.sh logs -n 50 # Display last 50 lines of Plex logs @@ -185,8 +461,17 @@ The `plex.sh` script is designed to work seamlessly with other Plex management s # Used by recovery scripts for service control ./recover-plex-database.sh # Uses plex.sh for service management +# Library scanner integration with service management +./plex.sh scan scan # Scan all libraries +./plex.sh scan refresh "" true # Force refresh all libraries after service restart + # Manual integration with porcelain output ./plex.sh --porcelain start # For use in scripts/automation + +# Scanner integration in maintenance scripts +./plex.sh scan scan # Regular media scanning +./plex.sh scan analyze # Weekly deep analysis +./plex.sh scan generate # Thumbnail regeneration ``` ### Security and Safety Features @@ -434,6 +719,11 @@ For scheduled operations: # Daily health check 0 6 * * * /home/acedanger/shell/plex/plex.sh status --validate + +# Automated library scanning (NEW) +0 4 * * * /home/acedanger/shell/plex/plex.sh scan scan # Daily scan for new media +0 2 * * 0 /home/acedanger/shell/plex/plex.sh scan refresh "" true # Weekly metadata refresh +0 1 * * 1 /home/acedanger/shell/plex/plex.sh scan analyze # Weekly media analysis ``` ## Exit Codes and Return Values