shell/plex/docs/plex-library-scanner.md

# 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)