new( \@paths, \%options )

Create a new Media::Scan instance and begin scanning.

paths may be a single scalar path, or an array reference with multiple paths.

options include:

loglevel (default: MS_LOG_ERR)

One of the following levels:

    MS_LOG_ERR
    MS_LOG_WARN
    MS_LOG_INFO
    MS_LOG_DEBUG
    MS_LOG_MEMORY
    

async (default: 0)

If set to 1, all scanning is performed in a background thread, and the call to new() will return immediately. Make sure to keep a reference to the Media::Scan object, or the scan will be aborted at DESTROY-time.

cachedir (default: current dir)

An optional path for libmediascan to store some cache files.

flags (default: MS_USE_EXTENSION | MS_FULL_SCAN)

An OR'ed list of flags, the possible flags are:

    MS_USE_EXTENSION   - Use a file's extension to determine how to scan it.
    MS_FULL_SCAN       - Perform a full scan on every file.
    MS_RESCAN          - Only scan files that are new or have changed since the last scan.
    MS_INCLUDE_DELETED - The result callback will be called for files that have been deleted
                         since the last scan.
    MS_WATCH_CHANGES   - Continue watching for changes after the scan has completed.
    MS_CLEARDB         - Wipe the internal libmediascan database before scanning.
    

ignore (default: none)

An array reference of file extensions that should be skipped. You may also specify 3 special types:

    AUDIO - Ignore all audio files.
    IMAGE - Ignore all image files.
    VIDEO - Ignore all video files.
    

ignore_dirs (default: none)

An array reference of directory substrings that should be skipped, for example the iTunes container directories ".ite" and ".itlp" or the Windows directory "RECYCLER". The substrings are case-sensitive.

thumbnails (default: none)

An arrayref of hashes with one or more thumbnail specifications. Thumbnails are created during the scanning process and are available within the result callback.

The format of a thumbnail spec is:

    { format => 'AUTO', # or JPEG or PNG
      width => 100,
      height => 100,
      keep_aspect => 1,
      bgcolor => 0xffffff,
      quality => 90,
    }
    

Most values are optional, however at least width or height must be specified.

on_result

A callback that will be called for each scanned file. The function will be passed a Media::Scan::Audio, Media::Scan::Video, or Media::Scan::Image depending on the file type. This callback is required.

on_error

An callback that will be called when a scanning error occurs. It is passed a Media::Scan::Error.

on_progress

An optional callback that will be passed a Media::Scan::Progress at regular intervals during scanning.

on_finish

An optional callback that is called when scanning has finished. Nothing is currently passed to this callback, eventually a scanning summary and overall stats might be included here.