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)

# Launch interactive scanner
plex scan

# Pass arguments directly to scanner
plex scan list
plex scan scan 29
plex scan refresh "" true

Direct Usage

# 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

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

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

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

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

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

# 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

#!/bin/bash
# Scan all libraries after adding new media
plex-scanner scan

# Force refresh if metadata seems outdated
plex-scanner refresh "" true

Maintenance Script

#!/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

#!/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:

plex-scanner -v list
plex-scanner -v scan 29

Log Analysis

Check logs for detailed error information:

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
• Plex Management Documentation
• Backup System Documentation