peterwood/shell
1
0
Fork 0
mirror of https://github.com/acedanger/shell.git synced 2025-12-05 22:50:18 -08:00
Code Issues 19 Packages Projects Releases Wiki Activity

feat: Enhance Plex management with library scanner integration and bash completion support

Browse Source
This commit is contained in:
Peter Wood
2025-06-26 09:15:24 -04:00
parent 563daa51af
commit 6e84bb33d6
4 changed files with 326 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

308
plex/plex-management.md
View File

@@ -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 <section_id>`** - 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 <TAB>
start stop restart status scan repair nuclear help
# Scanner sub-command completion
$ ./plex.sh scan <TAB>
list scan refresh analyze generate tree interactive -v --verbose -h --help
# Boolean flag completion for refresh and analyze
$ ./plex.sh scan refresh 29 <TAB>
true false
$ ./plex.sh scan analyze 29 <TAB>
true false
# Direct scanner completion
$ ./scan-plex-libraries.sh <TAB>
list scan refresh analyze generate tree interactive
# Alias completion
$ plex-scan <TAB>
list scan refresh analyze generate tree interactive
$ plex-scanner <TAB>
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
@@ -151,9 +416,20 @@ The script supports the following commands:
./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