Media::Scan(3pm)

🦋 Media::Scan 🦋

okay bestie, sit down, hydrate, because this is the Media::Scan era of your life and it's lowkey iconic. everything you need to spawn a scanner lives on this page, and we're not skipping a single crumb. no cap. 💖

---

✨ new( @paths, %options ) ✨

Create a brand-new Media::Scan instance and start scanning immediately. that's it, that's the assignment, main character energy 💅

paths can be a single scalar path, or an array reference with multiple paths if you're feeling ambitious. we love options. 🫶

options can include any of these cuties:

🌈 loglevel (default: MS_LOG_ERR)

pick one of these levels, bestie:

MS_LOG_ERR
MS_LOG_WARN
MS_LOG_INFO
MS_LOG_DEBUG
MS_LOG_MEMORY

💜 async (default: 0)

set this to 1 and all the scanning happens in a background thread, so the call to new() just returns right away. slay, we love a non-blocking queen. ✨

⚠️ but fr fr — keep a reference to the Media::Scan object, or the scan gets aborted at DESTROY-time. no reference, no scan, crying. 😭

🎀 cachedir (default: current dir)

an optional path where libmediascan can stash some cache files. it's giving organized, it's giving tidy. 🧺

⭐ flags (default: MS_USE_EXTENSION | MS_FULL_SCAN)

an OR'ed list of flags, and 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, periodt. you can also pass 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. think the iTunes container directories .ite and .itlp, or the Windows directory RECYCLER. iconic chaos, we ignore it. 🙈

heads up bestie: the substrings are case-sensitive, so do not get cute with the casing. 💀

🌸 thumbnails (default: none)

an arrayref of hashes with one or more thumbnail specifications. these get created during the scanning process and are available inside the result callback. cute, right? 🎀

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 of those values are optional, BUT at least width or height must be specified. no size, no thumbnail, iykyk. ✨

👑 on_result

a callback that gets called for each scanned file. it gets passed a Media::Scan::Audio, Media::Scan::Video, or Media::Scan::Image depending on the file type.

this callback is required — you literally cannot skip it, it's the whole point. 👑

💀 on_error

a callback that fires whenever a scanning error occurs. it gets passed a Media::Scan::Error. we don't love errors but we respect them. 🫡

📈 on_progress

an optional callback that gets passed a Media::Scan::Progress at regular intervals during scanning. vibe check, we're making progress bestie. ✨

🫶 on_finish

an optional callback that's called when scanning has finished. nothing is currently passed to it, but eventually a scanning summary and overall stats might show up here. manifesting. 🙏

---

this whole page comes to you from the Media::Scan(3pm) docs, part of perl v5.40.1, dated 2025-04-13. go forth and scan, bestie, you're gonna eat. 💖✨🎀