Repository Public
1// ORIX DJ2// File: Packages/ORIXDJCore/Sources/ORIXLibrary/MediaImporter.swift3// Description: Scans folders, validates audio files, reads tags and artwork with AVFoundation, imports into the library and resolves bookmarks.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai78@preconcurrency import AVFoundation9import Foundation10import ImageIO1112/// What `MediaImporter.readMetadata(url:)` learned about one audio file.13public struct ImportedMetadata: Sendable, Equatable {14 public var url: URL15 public var title: String16 public var artist: String17 public var album: String18 public var genre: String19 /// 0 when unknown.20 public var year: Int21 public var comment: String22 /// BPM written in the file tags, if any.23 public var bpm: Double?24 /// Initial-key tag as written in the file ("Am", "8A"…), if any.25 public var key: String?26 public var duration: Double27 public var sampleRate: Double28 public var channels: Int29 /// Bits per second (estimated from the file size when the container does not say).30 public var bitRate: Int31 public var format: String32 public var fileSize: Int6433 public var dateModified: Date34 /// JPEG thumbnail, longest side ≤ `MediaImporter.artworkMaxPixelSize`.35 public var artwork: Data?36 /// Plain file bookmark.37 public var bookmark: Data?3839 public init(url: URL, title: String, artist: String = "", album: String = "", genre: String = "", year: Int = 0,40 comment: String = "", bpm: Double? = nil, key: String? = nil, duration: Double, sampleRate: Double,41 channels: Int, bitRate: Int = 0, format: String, fileSize: Int64 = 0, dateModified: Date = Date(),42 artwork: Data? = nil, bookmark: Data? = nil) {43 self.url = url; self.title = title; self.artist = artist; self.album = album; self.genre = genre; self.year = year44 self.comment = comment; self.bpm = bpm; self.key = key; self.duration = duration; self.sampleRate = sampleRate45 self.channels = channels; self.bitRate = bitRate; self.format = format; self.fileSize = fileSize46 self.dateModified = dateModified; self.artwork = artwork; self.bookmark = bookmark47 }4849 /// A new library track (id 0) carrying this metadata.50 public func makeTrack(dateAdded: Date = Date()) -> Track {51 var camelot: String?52 var keyName = key53 if let key, MediaImporter.isCamelotCode(key) {54 camelot = key.uppercased()55 keyName = nil56 }57 return Track(path: url.path, bookmark: bookmark, title: title, artist: artist, album: album, genre: genre,58 year: year, comment: comment, duration: duration, sampleRate: sampleRate, channels: channels,59 bitRate: bitRate, format: format, fileSize: fileSize, dateAdded: dateAdded, dateModified: dateModified,60 bpm: bpm, key: keyName, camelot: camelot)61 }62}6364public struct ImportProgress: Sendable, Equatable {65 public var completed: Int66 public var total: Int67 public var currentURL: URL68}6970public struct ImportFailure: Sendable, Equatable {71 public var url: URL72 public var error: LibraryError73}7475public struct ImportSummary: Sendable, Equatable {76 /// Stored tracks (new or refreshed), in input order.77 public var imported: [Track] = []78 public var failures: [ImportFailure] = []79 /// `true` when the surrounding task was cancelled before every file was handled.80 public var cancelled = false81}8283/// Where the media of a track is now.84public struct ResolvedMedia: Sendable, Equatable {85 /// Current location, `nil` when the media cannot be found.86 public var url: URL?87 public var isMissing: Bool88 /// The file is no longer at `track.path` (moved or renamed) but was found through the bookmark.89 public var moved: Bool90 /// The stored bookmark was stale (or absent) and a fresh one was created.91 public var refreshedBookmark: Data?92}9394/// Stateless importer. Audio files are referenced in place: nothing is copied, moved or modified.95public struct MediaImporter: Sendable {96 /// Extensions accepted by `scan` and `readMetadata`. ALAC lives in `.m4a`. See97 /// `MediaImporterFormatTests` for what was verified to open with `AVAudioFile` on this macOS.98 public static let supportedExtensions: Set<String> = ["mp3", "wav", "aif", "aiff", "flac", "m4a", "aac", "caf"]99 public static let artworkMaxPixelSize = 300100101 public init() {}102103 // MARK: Scan104105 /// Expands files and folders into the supported audio files they contain, sorted by path, without duplicates.106 /// Hidden files and folders (dot-files, hidden flag) and package contents are skipped. Stops early, returning107 /// what was found so far, when the surrounding task is cancelled or `isCancelled` returns `true`.108 public func scan(urls: [URL], recursive: Bool = true, isCancelled: (@Sendable () -> Bool)? = nil) -> [URL] {109 let manager = FileManager.default110 var seen = Set<String>()111 var result: [URL] = []112 func cancelled() -> Bool { Task.isCancelled || (isCancelled?() ?? false) }113 func consider(_ url: URL) {114 guard MediaImporter.supportedExtensions.contains(url.pathExtension.lowercased()) else { return }115 let standard = url.standardizedFileURL116 if seen.insert(standard.path).inserted { result.append(standard) }117 }118 outer: for url in urls {119 if cancelled() { break }120 var isDirectory: ObjCBool = false121 guard manager.fileExists(atPath: url.path, isDirectory: &isDirectory) else { continue }122 if url.lastPathComponent.hasPrefix(".") { continue }123 if !isDirectory.boolValue {124 consider(url)125 continue126 }127 var options: FileManager.DirectoryEnumerationOptions = [.skipsHiddenFiles, .skipsPackageDescendants]128 if !recursive { options.insert(.skipsSubdirectoryDescendants) }129 guard let enumerator = manager.enumerator(at: url, includingPropertiesForKeys: [.isRegularFileKey, .isPackageKey],130 options: options, errorHandler: { _, _ in true }) else { continue }131 while let item = enumerator.nextObject() as? URL {132 if cancelled() { break outer }133 let values = try? item.resourceValues(forKeys: [.isRegularFileKey, .isPackageKey])134 if values?.isPackage == true {135 enumerator.skipDescendants()136 continue137 }138 if values?.isRegularFile == true { consider(item) }139 }140 }141 return result.sorted { $0.path.localizedStandardCompare($1.path) == .orderedAscending }142 }143144 // MARK: Validation and metadata145146 /// Cheap checks that need no decoding: supported extension, existing readable regular file, non-zero length.147 /// Returns the file size and modification date.148 @discardableResult149 public func validate(url: URL) throws -> (fileSize: Int64, dateModified: Date) {150 let path = url.path151 guard MediaImporter.supportedExtensions.contains(url.pathExtension.lowercased()) else {152 throw LibraryError.unsupportedFormat(path: path)153 }154 var isDirectory: ObjCBool = false155 guard FileManager.default.fileExists(atPath: path, isDirectory: &isDirectory), !isDirectory.boolValue else {156 throw LibraryError.unreadableFile(path: path, reason: "no such file")157 }158 guard FileManager.default.isReadableFile(atPath: path) else {159 throw LibraryError.unreadableFile(path: path, reason: "permission denied")160 }161 let attributes = try? FileManager.default.attributesOfItem(atPath: path)162 let size = (attributes?[.size] as? NSNumber)?.int64Value ?? 0163 guard size > 0 else { throw LibraryError.emptyFile(path: path) }164 return (size, (attributes?[.modificationDate] as? Date) ?? Date())165 }166167 /// Validates the file and reads its technical properties, tags and artwork. Throws `LibraryError`168 /// (`.unsupportedFormat`, `.emptyFile`, `.protectedContent`, `.unreadableFile`, `.cancelled`).169 public func readMetadata(url: URL) async throws -> ImportedMetadata {170 let url = url.standardizedFileURL171 let path = url.path172 let (fileSize, dateModified) = try validate(url: url)173174 let asset = AVURLAsset(url: url)175 var duration = 0.0176 var sampleRate = 0.0177 var channels = 0178 var bitRate = 0179 var assetReason: String?180 do {181 if try await asset.load(.hasProtectedContent) { throw LibraryError.protectedContent(path: path) }182 let audioTracks = try await asset.loadTracks(withMediaType: .audio)183 if let audio = audioTracks.first {184 let (time, rate, descriptions) = try await (asset.load(.duration), audio.load(.estimatedDataRate), audio.load(.formatDescriptions))185 if time.isNumeric { duration = time.seconds }186 bitRate = rate.isFinite && rate > 0 ? Int(rate.rounded()) : 0187 if let description = descriptions.first, let basic = CMAudioFormatDescriptionGetStreamBasicDescription(description)?.pointee {188 sampleRate = basic.mSampleRate189 channels = Int(basic.mChannelsPerFrame)190 }191 } else {192 assetReason = "no audio track"193 }194 } catch let error as LibraryError {195 throw error196 } catch is CancellationError {197 throw LibraryError.cancelled198 } catch {199 assetReason = error.localizedDescription200 }201202 // AVAudioFile is the reference for what the engine can decode; it also covers what AVURLAsset left unknown.203 if sampleRate <= 0 || channels <= 0 || duration <= 0 {204 do {205 let file = try AVAudioFile(forReading: url)206 let format = file.fileFormat207 sampleRate = format.sampleRate208 channels = Int(format.channelCount)209 if sampleRate > 0 { duration = Double(file.length) / sampleRate }210 } catch {211 throw LibraryError.unreadableFile(path: path, reason: assetReason ?? error.localizedDescription)212 }213 }214 guard sampleRate > 0, channels > 0, duration > 0, duration.isFinite else {215 throw LibraryError.unreadableFile(path: path, reason: assetReason ?? "no decodable audio")216 }217 if bitRate <= 0 { bitRate = Int((Double(fileSize) * 8 / duration).rounded()) }218219 var tags = TagValues()220 if assetReason == nil {221 var items: [AVMetadataItem] = []222 if let common = try? await asset.load(.commonMetadata) { items += common }223 if let all = try? await asset.load(.metadata) { items += all }224 await tags.read(items)225 }226227 let fileName = url.deletingPathExtension().lastPathComponent228 var title = tags.title229 var artist = tags.artist230 if title.isEmpty {231 let split = MediaImporter.splitFileName(fileName)232 title = split.title233 if artist.isEmpty, let fromName = split.artist { artist = fromName }234 }235236 return ImportedMetadata(237 url: url, title: title, artist: artist, album: tags.album, genre: tags.genre, year: tags.year,238 comment: tags.comment, bpm: tags.bpm, key: tags.key,239 duration: duration, sampleRate: sampleRate, channels: channels, bitRate: bitRate,240 format: url.pathExtension.lowercased(), fileSize: fileSize, dateModified: dateModified,241 artwork: tags.artwork.flatMap { MediaImporter.thumbnail(from: $0) },242 bookmark: MediaImporter.makeBookmark(for: url)243 )244 }245246 /// "Artist - Title" → (artist, title); anything else → (nil, name). Underscores are not touched.247 public static func splitFileName(_ name: String) -> (artist: String?, title: String) {248 let trimmed = name.trimmingCharacters(in: .whitespaces)249 for separator in [" - ", " – ", " — "] {250 if let range = trimmed.range(of: separator) {251 let artist = trimmed[..<range.lowerBound].trimmingCharacters(in: .whitespaces)252 let title = trimmed[range.upperBound...].trimmingCharacters(in: .whitespaces)253 if !artist.isEmpty, !title.isEmpty { return (artist, title) }254 }255 }256 return (nil, trimmed)257 }258259 static func isCamelotCode(_ text: String) -> Bool {260 let upper = text.trimmingCharacters(in: .whitespaces).uppercased()261 guard let letter = upper.last, letter == "A" || letter == "B", let number = Int(upper.dropLast()) else { return false }262 return (1...12).contains(number)263 }264265 /// Downscales image data to a JPEG whose longest side is at most `maxPixelSize`. `nil` when the data is not an image.266 public static func thumbnail(from imageData: Data, maxPixelSize: Int = MediaImporter.artworkMaxPixelSize) -> Data? {267 guard let source = CGImageSourceCreateWithData(imageData as CFData, nil) else { return nil }268 let options: [CFString: Any] = [269 kCGImageSourceCreateThumbnailFromImageAlways: true,270 kCGImageSourceCreateThumbnailWithTransform: true,271 kCGImageSourceThumbnailMaxPixelSize: maxPixelSize,272 ]273 guard let image = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else { return nil }274 let output = NSMutableData()275 guard let destination = CGImageDestinationCreateWithData(output, "public.jpeg" as CFString, 1, nil) else { return nil }276 CGImageDestinationAddImage(destination, image, [kCGImageDestinationLossyCompressionQuality: 0.8] as CFDictionary)277 guard CGImageDestinationFinalize(destination) else { return nil }278 return output as Data279 }280281 // MARK: Import282283 /// Reads and upserts each file (audio is not copied). Unreadable files are reported in `failures` and do not284 /// stop the import. Honours task cancellation between files. `progress` is called after each file, on the285 /// caller's executor.286 @discardableResult287 public func importFiles(_ urls: [URL], into store: LibraryStore,288 progress: (@Sendable (ImportProgress) -> Void)? = nil) async -> ImportSummary {289 var summary = ImportSummary()290 for (index, url) in urls.enumerated() {291 if Task.isCancelled {292 summary.cancelled = true293 break294 }295 do {296 let metadata = try await readMetadata(url: url)297 summary.imported.append(try store.upsertTrack(metadata.makeTrack(), artwork: metadata.artwork))298 } catch LibraryError.cancelled {299 summary.cancelled = true300 break301 } catch let error as LibraryError {302 summary.failures.append(ImportFailure(url: url, error: error))303 } catch {304 summary.failures.append(ImportFailure(url: url, error: .unreadableFile(path: url.path, reason: error.localizedDescription)))305 }306 progress?(ImportProgress(completed: index + 1, total: urls.count, currentURL: url))307 }308 return summary309 }310311 // MARK: Bookmarks312313 /// A plain (not security-scoped) bookmark, `nil` when the file does not exist.314 public static func makeBookmark(for url: URL) -> Data? {315 try? url.bookmarkData(options: [], includingResourceValuesForKeys: nil, relativeTo: nil)316 }317318 /// Finds the media of a track: through its bookmark first (follows moves and renames on the same volume),319 /// then at its stored path. Files in the Trash count as missing. Does not write to the library; see320 /// `resolve(track:updating:)`.321 public func resolve(track: Track) -> ResolvedMedia {322 let manager = FileManager.default323 func usable(_ url: URL) -> Bool {324 var isDirectory: ObjCBool = false325 guard manager.fileExists(atPath: url.path, isDirectory: &isDirectory), !isDirectory.boolValue else { return false }326 return !url.pathComponents.contains(".Trash") && !url.pathComponents.contains(".Trashes")327 }328 if let bookmark = track.bookmark {329 var stale = false330 if let resolved = try? URL(resolvingBookmarkData: bookmark, options: [.withoutUI, .withoutMounting],331 relativeTo: nil, bookmarkDataIsStale: &stale) {332 let url = resolved.standardizedFileURL333 if usable(url) {334 let moved = url.path != track.path335 let refreshed = (stale || moved) ? MediaImporter.makeBookmark(for: url) : nil336 return ResolvedMedia(url: url, isMissing: false, moved: moved, refreshedBookmark: refreshed)337 }338 }339 }340 let stored = URL(fileURLWithPath: track.path)341 if usable(stored) {342 // No usable bookmark, but the file is where the library says: give it a fresh bookmark.343 return ResolvedMedia(url: stored, isMissing: false, moved: false, refreshedBookmark: MediaImporter.makeBookmark(for: stored))344 }345 return ResolvedMedia(url: nil, isMissing: true, moved: false, refreshedBookmark: nil)346 }347348 /// `resolve(track:)` that also persists the outcome: relocates a moved track, stores a refreshed bookmark,349 /// sets or clears the `missing` flag. Returns the resolution and the track as stored afterwards.350 public func resolve(track: Track, updating store: LibraryStore) throws -> (media: ResolvedMedia, track: Track) {351 let media = resolve(track: track)352 var current = track353 if media.isMissing {354 if !track.missing {355 try store.markMissing(trackIDs: [track.id], missing: true)356 current.missing = true357 }358 } else if let url = media.url, media.moved {359 current = try store.relocate(trackID: track.id, to: url)360 } else if media.refreshedBookmark != nil || track.missing {361 if var stored = try store.track(id: track.id) {362 stored.bookmark = media.refreshedBookmark ?? stored.bookmark363 stored.missing = false364 current = try store.updateTrack(stored)365 }366 }367 return (media, current)368 }369}370371// MARK: - Tag extraction372373private struct TagValues {374 var title = ""375 var artist = ""376 var album = ""377 var genre = ""378 var year = 0379 var comment = ""380 var bpm: Double?381 var key: String?382 var artwork: Data?383384 mutating func read(_ items: [AVMetadataItem]) async {385 for item in items {386 let identifier = item.identifier387 let rawKey = MediaImporter_keyString(item)388 switch identifier {389 case AVMetadataIdentifier.commonIdentifierTitle?, AVMetadataIdentifier.id3MetadataTitleDescription?,390 AVMetadataIdentifier.iTunesMetadataSongName?:391 if title.isEmpty { title = await string(item) }392 case AVMetadataIdentifier.commonIdentifierArtist?, AVMetadataIdentifier.id3MetadataLeadPerformer?,393 AVMetadataIdentifier.iTunesMetadataArtist?:394 if artist.isEmpty { artist = await string(item) }395 case AVMetadataIdentifier.commonIdentifierAlbumName?, AVMetadataIdentifier.id3MetadataAlbumTitle?,396 AVMetadataIdentifier.iTunesMetadataAlbum?:397 if album.isEmpty { album = await string(item) }398 case AVMetadataIdentifier.id3MetadataContentType?, AVMetadataIdentifier.iTunesMetadataUserGenre?,399 AVMetadataIdentifier.quickTimeUserDataGenre?, AVMetadataIdentifier.quickTimeMetadataGenre?,400 AVMetadataIdentifier.commonIdentifierType?:401 if genre.isEmpty { genre = TagValues.genreName(await string(item)) }402 case AVMetadataIdentifier.iTunesMetadataPredefinedGenre?:403 if genre.isEmpty, let number = try? await item.load(.numberValue) {404 // iTunes "gnre" is the ID3v1 index + 1.405 genre = TagValues.genreName(String(number.intValue - 1), numericOnly: true)406 }407 case AVMetadataIdentifier.id3MetadataYear?, AVMetadataIdentifier.id3MetadataRecordingTime?,408 AVMetadataIdentifier.id3MetadataOriginalReleaseYear?, AVMetadataIdentifier.iTunesMetadataReleaseDate?,409 AVMetadataIdentifier.commonIdentifierCreationDate?, AVMetadataIdentifier.quickTimeMetadataYear?:410 if year == 0 { year = TagValues.year(await string(item)) }411 case AVMetadataIdentifier.id3MetadataComments?, AVMetadataIdentifier.iTunesMetadataUserComment?,412 AVMetadataIdentifier.commonIdentifierDescription?, AVMetadataIdentifier.quickTimeMetadataComment?:413 if comment.isEmpty { comment = await string(item) }414 case AVMetadataIdentifier.id3MetadataBeatsPerMinute?, AVMetadataIdentifier.iTunesMetadataBeatsPerMin?:415 if bpm == nil { bpm = await number(item) }416 case AVMetadataIdentifier.id3MetadataInitialKey?:417 if key == nil { key = await nonEmpty(item) }418 case AVMetadataIdentifier.commonIdentifierArtwork?, AVMetadataIdentifier.id3MetadataAttachedPicture?,419 AVMetadataIdentifier.iTunesMetadataCoverArt?:420 if artwork == nil { artwork = try? await item.load(.dataValue) }421 default:422 // Free-form atoms and Vorbis-style keys ("initialkey", "KEY", "BPM", "TEMPO").423 let lowered = rawKey.lowercased()424 if key == nil, lowered.hasSuffix("initialkey") || lowered == "key" || lowered == "initial key" {425 key = await nonEmpty(item)426 } else if bpm == nil, lowered == "bpm" || lowered == "tempo" || lowered.hasSuffix(":bpm") {427 bpm = await number(item)428 }429 }430 }431 if let value = bpm, !(value > 0 && value < 1000) { bpm = nil }432 }433434 private func string(_ item: AVMetadataItem) async -> String {435 if let text = try? await item.load(.stringValue) { return text.trimmingCharacters(in: .whitespacesAndNewlines) }436 if let number = try? await item.load(.numberValue) { return number.stringValue }437 return ""438 }439440 private func nonEmpty(_ item: AVMetadataItem) async -> String? {441 let text = await string(item)442 return text.isEmpty ? nil : text443 }444445 private func number(_ item: AVMetadataItem) async -> Double? {446 if let number = try? await item.load(.numberValue) { return number.doubleValue }447 if let text = try? await item.load(.stringValue) {448 return Double(text.trimmingCharacters(in: .whitespaces).replacingOccurrences(of: ",", with: "."))449 }450 return nil451 }452453 static func year(_ text: String) -> Int {454 let digits = text.prefix(while: { $0.isNumber })455 guard digits.count >= 4, let value = Int(digits.prefix(4)), (1000...9999).contains(value) else { return 0 }456 return value457 }458459 /// Resolves ID3v1 numeric genres ("17", "(17)", "(17)Rock") to their names; other text is returned as is.460 static func genreName(_ text: String, numericOnly: Bool = false) -> String {461 var candidate = text462 if candidate.hasPrefix("("), let close = candidate.firstIndex(of: ")") {463 let inside = candidate[candidate.index(after: candidate.startIndex)..<close]464 let rest = candidate[candidate.index(after: close)...].trimmingCharacters(in: .whitespaces)465 if !rest.isEmpty { return rest }466 candidate = String(inside)467 }468 if let index = Int(candidate) {469 return id3Genres.indices.contains(index) ? id3Genres[index] : (numericOnly ? "" : text)470 }471 return numericOnly ? "" : text472 }473474 static let id3Genres: [String] = [475 "Blues", "Classic Rock", "Country", "Dance", "Disco", "Funk", "Grunge", "Hip-Hop", "Jazz", "Metal",476 "New Age", "Oldies", "Other", "Pop", "R&B", "Rap", "Reggae", "Rock", "Techno", "Industrial",477 "Alternative", "Ska", "Death Metal", "Pranks", "Soundtrack", "Euro-Techno", "Ambient", "Trip-Hop", "Vocal", "Jazz+Funk",478 "Fusion", "Trance", "Classical", "Instrumental", "Acid", "House", "Game", "Sound Clip", "Gospel", "Noise",479 "Alternative Rock", "Bass", "Soul", "Punk", "Space", "Meditative", "Instrumental Pop", "Instrumental Rock", "Ethnic", "Gothic",480 "Darkwave", "Techno-Industrial", "Electronic", "Pop-Folk", "Eurodance", "Dream", "Southern Rock", "Comedy", "Cult", "Gangsta",481 "Top 40", "Christian Rap", "Pop/Funk", "Jungle", "Native American", "Cabaret", "New Wave", "Psychedelic", "Rave", "Showtunes",482 "Trailer", "Lo-Fi", "Tribal", "Acid Punk", "Acid Jazz", "Polka", "Retro", "Musical", "Rock & Roll", "Hard Rock",483 ]484}485486/// The raw key of a metadata item as text (free-form iTunes atoms, Vorbis comments).487private func MediaImporter_keyString(_ item: AVMetadataItem) -> String {488 if let key = item.key as? String { return key }489 if let identifier = item.identifier?.rawValue { return identifier }490 return ""491}492