mirror of
https://github.com/acedanger/shell.git
synced 2025-12-06 02:20:11 -08:00
added the ability to initiate a plex library scan from the CLI. tab completions are supported as well.
This commit is contained in:
Peter Wood
342
plex/docs/plex-library-scanner.md
Normal file
342
plex/docs/plex-library-scanner.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# Plex Library Scanner Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The Plex Library Scanner provides a comprehensive command-line interface for managing Plex Media Server libraries. It wraps the native Plex Media Scanner binary with enhanced functionality, error handling, and user-friendly output.
|
||||
|
||||
## Features
|
||||
|
||||
- **Library Management**: List, scan, refresh, and analyze Plex libraries
|
||||
- **Interactive Mode**: User-friendly menu system for easy operation
|
||||
- **Batch Operations**: Perform operations on all libraries or specific ones
|
||||
- **Enhanced Output**: Colored, styled terminal output with progress indicators
|
||||
- **Error Handling**: Comprehensive validation and error reporting
|
||||
- **Logging**: Detailed operation logs for troubleshooting
|
||||
|
||||
## Scripts
|
||||
|
||||
### scan-plex-libraries.sh
|
||||
Primary script for library scanning operations.
|
||||
|
||||
**Location**: `/home/acedanger/shell/plex/scan-plex-libraries.sh`
|
||||
|
||||
**Features**:
|
||||
- Automatic detection of Plex Media Scanner binary
|
||||
- Service status validation
|
||||
- Section ID validation
|
||||
- Comprehensive error handling
|
||||
- Interactive and command-line modes
|
||||
|
||||
### Integration with plex.sh
|
||||
The scanner is integrated into the main `plex.sh` script as the `scan` command.
|
||||
|
||||
## Usage
|
||||
|
||||
### Via plex.sh (Recommended)
|
||||
```bash
|
||||
# Launch interactive scanner
|
||||
plex scan
|
||||
|
||||
# Pass arguments directly to scanner
|
||||
plex scan list
|
||||
plex scan scan 29
|
||||
plex scan refresh "" true
|
||||
```
|
||||
|
||||
### Direct Usage
|
||||
```bash
|
||||
# Interactive mode
|
||||
./scan-plex-libraries.sh
|
||||
|
||||
# List all libraries
|
||||
./scan-plex-libraries.sh list
|
||||
|
||||
# Scan specific library
|
||||
./scan-plex-libraries.sh scan 29
|
||||
|
||||
# Scan all libraries
|
||||
./scan-plex-libraries.sh scan
|
||||
|
||||
# Refresh with force flag
|
||||
./scan-plex-libraries.sh refresh 29 true
|
||||
|
||||
# Deep analysis
|
||||
./scan-plex-libraries.sh analyze 29 true
|
||||
|
||||
# Generate thumbnails
|
||||
./scan-plex-libraries.sh generate 29
|
||||
|
||||
# Show library tree
|
||||
./scan-plex-libraries.sh tree 29
|
||||
```
|
||||
|
||||
### Via Aliases
|
||||
```bash
|
||||
# Using new aliases
|
||||
plex-scan # Launch scanner via plex.sh
|
||||
plex-scanner # Direct access to scanner script
|
||||
plex-scanner list # List libraries directly
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### list
|
||||
Lists all available library sections with their IDs and names.
|
||||
|
||||
**Usage**: `scan-plex-libraries.sh list`
|
||||
|
||||
**Output**:
|
||||
```
|
||||
Available Library Sections:
|
||||
=========================
|
||||
29: Movies
|
||||
30: TV Shows
|
||||
31: Music
|
||||
```
|
||||
|
||||
### scan
|
||||
Scans libraries for new media files.
|
||||
|
||||
**Usage**:
|
||||
- `scan-plex-libraries.sh scan` (all libraries)
|
||||
- `scan-plex-libraries.sh scan <section_id>` (specific library)
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# Scan all libraries
|
||||
scan-plex-libraries.sh scan
|
||||
|
||||
# Scan Movies library (ID 29)
|
||||
scan-plex-libraries.sh scan 29
|
||||
```
|
||||
|
||||
### refresh
|
||||
Refreshes metadata for library items.
|
||||
|
||||
**Usage**:
|
||||
- `scan-plex-libraries.sh refresh [section_id] [force]`
|
||||
|
||||
**Parameters**:
|
||||
- `section_id`: Library section ID (optional, scans all if omitted)
|
||||
- `force`: Set to "true" for forced refresh (optional)
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# Refresh all libraries
|
||||
scan-plex-libraries.sh refresh
|
||||
|
||||
# Refresh specific library
|
||||
scan-plex-libraries.sh refresh 29
|
||||
|
||||
# Force refresh all libraries
|
||||
scan-plex-libraries.sh refresh "" true
|
||||
|
||||
# Force refresh specific library
|
||||
scan-plex-libraries.sh refresh 29 true
|
||||
```
|
||||
|
||||
### analyze
|
||||
Analyzes media files for metadata and codec information.
|
||||
|
||||
**Usage**:
|
||||
- `scan-plex-libraries.sh analyze [section_id] [deep]`
|
||||
|
||||
**Parameters**:
|
||||
- `section_id`: Library section ID (optional)
|
||||
- `deep`: Set to "true" for deep analysis (optional)
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# Analyze all libraries
|
||||
scan-plex-libraries.sh analyze
|
||||
|
||||
# Analyze specific library
|
||||
scan-plex-libraries.sh analyze 29
|
||||
|
||||
# Deep analyze all libraries
|
||||
scan-plex-libraries.sh analyze "" true
|
||||
|
||||
# Deep analyze specific library
|
||||
scan-plex-libraries.sh analyze 29 true
|
||||
```
|
||||
|
||||
### generate
|
||||
Generates thumbnails and fanart for media items.
|
||||
|
||||
**Usage**:
|
||||
- `scan-plex-libraries.sh generate [section_id]`
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# Generate for all libraries
|
||||
scan-plex-libraries.sh generate
|
||||
|
||||
# Generate for specific library
|
||||
scan-plex-libraries.sh generate 29
|
||||
```
|
||||
|
||||
### tree
|
||||
Shows the hierarchical structure of a library.
|
||||
|
||||
**Usage**:
|
||||
- `scan-plex-libraries.sh tree <section_id>`
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
# Show Movies library structure
|
||||
scan-plex-libraries.sh tree 29
|
||||
```
|
||||
|
||||
### interactive
|
||||
Launches the interactive menu system.
|
||||
|
||||
**Usage**: `scan-plex-libraries.sh interactive` (or just `scan-plex-libraries.sh`)
|
||||
|
||||
## Options
|
||||
|
||||
### -v, --verbose
|
||||
Enables verbose output showing detailed progress information.
|
||||
|
||||
**Usage**: `scan-plex-libraries.sh -v <command>`
|
||||
|
||||
### -h, --help
|
||||
Shows help information and usage examples.
|
||||
|
||||
**Usage**: `scan-plex-libraries.sh --help`
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Plex Media Server**: Must be installed and running
|
||||
2. **Plex Media Scanner**: Binary must be available (automatically detected)
|
||||
3. **Permissions**: Script must be run with appropriate user permissions
|
||||
4. **Service Access**: Access to systemctl for service status checking
|
||||
|
||||
## Automatic Detection
|
||||
|
||||
The scanner automatically detects the Plex Media Scanner binary from these locations:
|
||||
- `/usr/lib/plexmediaserver/Plex Media Scanner` (Linux - most common)
|
||||
- `/opt/plex/Plex Media Scanner` (Alternative Linux)
|
||||
- `/usr/local/plex/Plex Media Scanner` (Custom installations)
|
||||
- `/Applications/Plex Media Server.app/Contents/MacOS/Plex Media Scanner` (macOS)
|
||||
- System PATH
|
||||
|
||||
## Error Handling
|
||||
|
||||
The script provides comprehensive error handling for:
|
||||
- Missing Plex Media Scanner binary
|
||||
- Plex service not running
|
||||
- Invalid section IDs
|
||||
- Scanner operation failures
|
||||
- Permission issues
|
||||
|
||||
## Logging
|
||||
|
||||
Operations are logged to: `/home/acedanger/shell/logs/plex-scanner.log`
|
||||
|
||||
Log entries include:
|
||||
- Timestamp
|
||||
- Operation type
|
||||
- Success/failure status
|
||||
- Error details (if applicable)
|
||||
- Debug information (in verbose mode)
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Automated Scanning
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Scan all libraries after adding new media
|
||||
plex-scanner scan
|
||||
|
||||
# Force refresh if metadata seems outdated
|
||||
plex-scanner refresh "" true
|
||||
```
|
||||
|
||||
### Maintenance Script
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Daily maintenance routine
|
||||
echo "Starting Plex maintenance..."
|
||||
|
||||
# Scan for new media
|
||||
plex-scanner scan
|
||||
|
||||
# Analyze any new files
|
||||
plex-scanner analyze
|
||||
|
||||
# Generate missing thumbnails
|
||||
plex-scanner generate
|
||||
|
||||
echo "Maintenance complete!"
|
||||
```
|
||||
|
||||
### Specific Library Management
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Update specific library after batch media addition
|
||||
MOVIES_ID=29
|
||||
TV_SHOWS_ID=30
|
||||
|
||||
# Scan and refresh movies
|
||||
plex-scanner scan $MOVIES_ID
|
||||
plex-scanner refresh $MOVIES_ID true
|
||||
|
||||
# Deep analyze TV shows
|
||||
plex-scanner analyze $TV_SHOWS_ID true
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **"Plex Media Server is not running"**
|
||||
- Start Plex: `sudo systemctl start plexmediaserver`
|
||||
- Check status: `systemctl status plexmediaserver`
|
||||
|
||||
2. **"Plex Media Scanner binary not found"**
|
||||
- Verify Plex installation
|
||||
- Check if binary exists in expected locations
|
||||
- Ensure proper PATH configuration
|
||||
|
||||
3. **"Section ID not found"**
|
||||
- Use `plex-scanner list` to see valid section IDs
|
||||
- Ensure the library hasn't been deleted
|
||||
|
||||
4. **Permission denied errors**
|
||||
- Don't run as root
|
||||
- Ensure user has access to Plex directories
|
||||
- Check file permissions on scanner binary
|
||||
|
||||
### Debug Mode
|
||||
Enable verbose logging for troubleshooting:
|
||||
```bash
|
||||
plex-scanner -v list
|
||||
plex-scanner -v scan 29
|
||||
```
|
||||
|
||||
### Log Analysis
|
||||
Check logs for detailed error information:
|
||||
```bash
|
||||
tail -f /home/acedanger/shell/logs/plex-scanner.log
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **Large Libraries**: Operations on large libraries may take considerable time
|
||||
- **Deep Analysis**: Deep analysis is resource-intensive, use sparingly
|
||||
- **Concurrent Operations**: Avoid running multiple scanner operations simultaneously
|
||||
- **System Resources**: Scanner operations can be CPU and I/O intensive
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Regular Scanning**: Set up regular scans for libraries with frequent additions
|
||||
2. **Selective Operations**: Use specific section IDs for targeted operations
|
||||
3. **Monitor Logs**: Regular log review helps identify issues early
|
||||
4. **Test First**: Use verbose mode to understand operation impact
|
||||
5. **Service Health**: Ensure Plex service is healthy before operations
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Plex Media Scanner CLI Documentation](https://support.plex.tv/articles/201242707-plex-media-scanner-via-command-line/)
|
||||
- [Plex Management Documentation](plex-management.md)
|
||||
- [Backup System Documentation](plex-backup.md)
|
||||
Reference in New Issue
Block a user