/ 
App-Plex-Archiver-0.01
/ App::Plex::Archiver

NAME

App::Plex::Archiver - Core functionality for archiving Plex media files

SYNOPSIS

use App::Plex::Archiver qw( title_from_filename copy_file get_tmbd_api_key get_tmdb_info );

# Extract a title from a filename
my $title = title_from_filename('/path/to/movie_file-2023.mp4');
# Returns: "Movie File 2023"

# Copy or move a file
copy_file('/source/file.mp4', '/dest/file.mp4', 0);  # Copy
copy_file('/source/file.mp4', '/dest/file.mp4', 1);  # Move

# Get TMDB API key
my ($error, $api_key) = get_tmbd_api_key();
die $error if $error;

# Search for movie information
my $tmdb = TMDB->new(api_key => $api_key);
my ($tmdb_id, $release_year) = get_tmdb_info($tmdb, "Movie Title", 1);

DESCRIPTION

App::Plex::Archiver provides core functionality for archiving media files into a directory structure suitable for Plex Media Server. The module handles file operations, filename processing, TMDB API integration, and user interaction for movie metadata retrieval.

This module is designed to work with the plex-archiver command-line tool but can be used independently for media file processing tasks.

EXPORTED FUNCTIONS

The following functions can be imported using the use statement:

title_from_filename

my $title = title_from_filename($filename);

Extracts a human-readable title from a filename by removing the path and extension, converting underscores and dashes to spaces, and applying proper title case formatting.

  • Parameters

    • $filename - The full path or filename to process

  • Returns

    A properly formatted title string, or empty string if no filename provided

  • Example

    title_from_filename('/movies/the_dark_knight-2008.mp4')
# Returns: "The Dark Knight 2008"

copy_file

copy_file($source, $destination, $delete_source);

Safely copies a file from source to destination with optional deletion of the source file (move operation). Includes comprehensive error checking and validation.

  • Parameters

    • $source - Path to the source file

    • $destination - Path to the destination file

    • $delete_source - Boolean flag: if true, deletes source after successful copy

  • Returns

    Nothing on success. Dies with descriptive error message on failure.

  • Validation

    • Verifies source file exists and is readable

    • Verifies destination directory is writable

    • Ensures atomic operation (copy then delete for moves)

get_tmbd_api_key

my ($error, $api_key) = get_tmbd_api_key($filename);

Retrieves the TMDB API key from a specified file or searches for it in default locations (current directory and user home directory).

  • Parameters

    • $filename - Optional: specific file containing the API key

  • Returns

    A two-element list:

    • $error - Error message string, or undef on success

    • $api_key - The API key string, or undef on error

  • Default Search Locations

    • ./.tmdb-api-key (current directory)

    • $HOME/.tmdb-api-key (user home directory)

get_tmdb_info

my ($tmdb_id, $release_year) = get_tmdb_info($tmdb, $title, $debug);

Searches TMDB for movie information and presents an interactive menu for the user to select the correct match. Returns the TMDB ID and release year for the selected movie.

  • Parameters

    • $tmdb - TMDB object instance (from TMDB module)

    • $title - Movie title to search for

    • $debug - Optional: enable debug output (default: 0)

  • Returns

    A two-element list on success, or empty list if no selection made:

    • $tmdb_id - TMDB movie ID

    • $release_year - Movie release year (extracted from release_date)

  • Interactive Features

    • Presents numbered menu of search results

    • Shows movie title and release year for each option

    • Handles user selection via IO::Prompter

DEPENDENCIES

This module requires the following Perl modules:

CONSTANTS

$DEFAULT_TMDB_API_KEY_FILENAME

The default filename to search for when looking for TMDB API key files.

Default value: ".tmdb-api-key"

ERROR HANDLING

Functions in this module use different error handling strategies:

  • copy_file - Dies with descriptive error messages using croak

  • get_tmbd_api_key - Returns error message as first return value

  • title_from_filename - Returns empty string for invalid input

  • get_tmdb_info - Returns empty list when no selection is made

EXAMPLES

Basic File Processing

use App::Plex::Archiver qw( title_from_filename copy_file );

my $source = '/downloads/movie_file_2023.mkv';
my $title = title_from_filename($source);
my $dest = "/plex/movies/$title/$title.mkv";

# Create destination directory
use File::Path qw( make_path );
make_path(dirname($dest));

# Copy file
copy_file($source, $dest, 0);

TMDB Integration

use App::Plex::Archiver qw( get_tmbd_api_key get_tmdb_info );
use TMDB;

# Get API key
my ($error, $api_key) = get_tmbd_api_key();
die "Failed to get API key: $error" if $error;

# Initialize TMDB
my $tmdb = TMDB->new(api_key => $api_key);

# Search for movie
my ($tmdb_id, $year) = get_tmdb_info($tmdb, "The Matrix", 1);
if ($tmdb_id) {
    print "Found: TMDB ID $tmdb_id, Year $year\n";
}

VERSION

Version 0.01

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

This module was created as part of the plex-archiver project.

SEE ALSO