---
name: "Media::Scan"
section: "3pm"
platform: "linux"
package: "libmedia-scan-perl"
version: "0~20220401.git.34fc2d-7"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Media::Scan"
---

# Media::Scan(3pm)

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