SPB Git

Repository Public

MediaImporter.swift 24.8 KB 492 lines swift

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
Files main
Menu

Theme