Mac Developer Library

Developer

MediaLibrary Framework Reference MLMediaLibrary Class Reference

Options
Deployment Target:

On This Page
Language:

MLMediaLibrary

The MLMediaLibrary class provides an interface for accessing a collection of media objects from various sources. It serves as the initial access point of the Media Library framework.

The media library structure is defined by MLMediaSource, MLMediaGroup, and MLMediaObject classes. At the highest level, all content within a media library instance is categorized by media source. Conceptually, a media source respresents a single app, such as iTunes or Aperture. Each source contains a hierarchy of media groups that originates from a root group. These groups consist of media objects—individual files containing a piece of media such as a photo, song, or movie. Only one copy of each object exists within a media library instance, but an object can be referenced by multiple groups from a single source. The structure of the group hierarchy is specific to each media source.

Figure 1Sample structure of an MLMediaLibrary instance image: ../Art/MediaLibraryHierarchy_2x.png

A media library is initialized using the initWithOptions: method. The options argument to this method serves as a filter. By specifying which folders or sources to include or exclude during load, you can view a particular subset of groups and objects from your collection. All objects provided are thread-safe. For descriptions of possible load options, see Load Options Keys.

The typical and most efficient use case is to create and use one instance of MLMediaLibrary for the lifetime of an app. When the underlying media files and metadata on the user’s system change, the corresponding data model objects (media groups and media objects) are automatically updated and KVO notifications are sent to notify the calling code of any changes. Multiple instances of MLMediaLibrary can be created and used, but their sources, groups, and objects will be independent of those provided by other instances of MLMediaLibrary.

Inheritance


Conforms To


Import Statement


Swift

import MediaLibrary

Objective-C

@import MediaLibrary;

Availability


Available in OS X v10.9 and later.
  • init(options:) - initWithOptions: Designated Initializer

    Initializes the media library based on the specified load options.

    Declaration

    Swift

    init!(options options: [NSObject : AnyObject]!)

    Objective-C

    - (instancetype)initWithOptions:(NSDictionary *)options

    Parameters

    options

    A dictionary of load options.

    Return Value

    A new media library.

    Discussion

    For descriptions of possible load options, see Load Options Keys.

    Import Statement

    Objective-C

    @import MediaLibrary;

    Swift

    import MediaLibrary

    Availability

    Available in OS X v10.9 and later.

  • Returns a dictionary of media sources by identifier. (read-only)

    Declaration

    Swift

    var mediaSources: [NSObject : AnyObject]! { get }

    Objective-C

    @property(readonly, copy) NSDictionary *mediaSources

    Discussion

    Returns nil the first time, beginning an asynchronous load of the media sources. A KVO notification is sent when all media sources have been loaded. If there are no objects in a media source, the source does not appear in this dictionary.

    Import Statement

    Objective-C

    @import MediaLibrary;

    Swift

    import MediaLibrary

    Availability

    Available in OS X v10.9 and later.

  • Keys used to specify the options dictionary argument to initWithOptions:.

    Declaration

    Swift

    let MLMediaLoadSourceTypesKey: NSString! let MLMediaLoadIncludeSourcesKey: NSString! let MLMediaLoadExcludeSourcesKey: NSString! let MLMediaLoadFoldersKey: NSString! let MLMediaLoadAppFoldersKey: NSString!

    Objective-C

    NSString* const MLMediaLoadSourceTypesKey; NSString* const MLMediaLoadIncludeSourcesKey; NSString* const MLMediaLoadExcludeSourcesKey; NSString* const MLMediaLoadFoldersKey; NSString* const MLMediaLoadAppFoldersKey;

    Constants

    • MLMediaLoadSourceTypesKey

      MLMediaLoadSourceTypesKey

      Defines which sources to load based on library type. If not present, this will load all sources. The value for this key is a media source type. For a list of valid media source types, see MLMediaSourceType.

      Available in OS X v10.9 and later.

    • MLMediaLoadIncludeSourcesKey

      MLMediaLoadIncludeSourcesKey

      Defines which media sources to include when loading. If not present, load all available media sources. This option is processed after MLMediaLoadSourceTypesKey. If MLMediaLoadIncludeSourcesKey is present but MLMediaLoadSourceTypesKey is not, then only those sources specified here will be loaded. This is useful for loading a single media source. When both keys are present, this is useful for adding one or more media sources that normally would not appear for the requested library type. The value for this key is an array of strings (media source identifiers). For a list of valid media source identifiers, see Media Source Identifiers.

      Available in OS X v10.9 and later.

    • MLMediaLoadExcludeSourcesKey

      MLMediaLoadExcludeSourcesKey

      Defines which media sources to exclude when loading. This option is processed after MLMediaLoadIncludeSourcesKey. The value for this key is an array of strings (media source identifiers). For a list of valid media source identifiers, see Media Source Identifiers.

      Available in OS X v10.9 and later.

    • MLMediaLoadFoldersKey

      MLMediaLoadFoldersKey

      Specifies the well-known folders that should be searched for media files. If this key is not present, none of the well-known folders will be provided. The value for this key is an array of strings (identifiers that correspond to well-known folder locations). For a list of well-known folder identifiers, see Well-Known Folder Identifiers.

      Available in OS X v10.9 and later.

    • MLMediaLoadAppFoldersKey

      MLMediaLoadAppFoldersKey

      Specifies one or more relative paths inside the caller’s app bundle in which to search for media files. The value for this key is an array of strings (relative paths inside the caller’s app bundle).

      Available in OS X v10.9 and later.

  • Identifiers for media sources which correspond to apps used to manage groups of media objects. Used with Load Options Keys.

    Declaration

    Swift

    let MLMediaSourceiPhotoIdentifier: NSString! let MLMediaSourceiTunesIdentifier: NSString! let MLMediaSourceApertureIdentifier: NSString! let MLMediaSourceiMovieIdentifier: NSString! let MLMediaSourceFinalCutIdentifier: NSString! let MLMediaSourceGarageBandIdentifier: NSString! let MLMediaSourceLogicIdentifier: NSString! let MLMediaSourcePhotoBoothIdentifier: NSString!

    Objective-C

    NSString* const MLMediaSourceiPhotoIdentifier; NSString* const MLMediaSourceiTunesIdentifier; NSString* const MLMediaSourceApertureIdentifier; NSString* const MLMediaSourceiMovieIdentifier; NSString* const MLMediaSourceFinalCutIdentifier; NSString* const MLMediaSourceGarageBandIdentifier; NSString* const MLMediaSourceLogicIdentifier; NSString* const MLMediaSourcePhotoBoothIdentifier;

    Constants

    • MLMediaSourceiPhotoIdentifier

      MLMediaSourceiPhotoIdentifier

      The media source providing content from iPhoto.

      Available in OS X v10.9 and later.

    • MLMediaSourceiTunesIdentifier

      MLMediaSourceiTunesIdentifier

      The media source providing content from iTunes.

      Available in OS X v10.9 and later.

    • MLMediaSourceApertureIdentifier

      MLMediaSourceApertureIdentifier

      The media source providing content from Aperture.

      Available in OS X v10.9 and later.

    • MLMediaSourceiMovieIdentifier

      MLMediaSourceiMovieIdentifier

      The media source providing content from iMovie.

      Available in OS X v10.9 and later.

    • MLMediaSourceFinalCutIdentifier

      MLMediaSourceFinalCutIdentifier

      The media source providing content from Final Cut Pro.

      Available in OS X v10.9 and later.

    • MLMediaSourceGarageBandIdentifier

      MLMediaSourceGarageBandIdentifier

      The media source providing content from GarageBand.

      Available in OS X v10.9 and later.

    • MLMediaSourceLogicIdentifier

      MLMediaSourceLogicIdentifier

      The media source providing content from Logic.

      Available in OS X v10.9 and later.

    • MLMediaSourcePhotoBoothIdentifier

      MLMediaSourcePhotoBoothIdentifier

      The media source providing content from Photo Booth.

      Available in OS X v10.9 and later.

  • Identifiers for media sources which do not correspond to apps. Used with Load Options Keys.

    Declaration

    Swift

    let MLMediaSourceMoviesFolderIdentifier: NSString! let MLMediaSourceCustomFoldersIdentifier: NSString! let MLMediaSourceAppDefinedFoldersIdentifier: NSString!

    Objective-C

    NSString* const MLMediaSourceMoviesFolderIdentifier; NSString* const MLMediaSourceCustomFoldersIdentifier; NSString* const MLMediaSourceAppDefinedFoldersIdentifier;

    Constants

    • MLMediaSourceMoviesFolderIdentifier

      MLMediaSourceMoviesFolderIdentifier

      The media source for the user’s Movies folder. This source provides data when MLMediaLoadFoldersKey is provided with the MLMediaLoadMoviesFolder value.

      Available in OS X v10.9 and later.

    • MLMediaSourceCustomFoldersIdentifier

      MLMediaSourceCustomFoldersIdentifier

      The media source for custom folders. Currently, the only custom folder is the folder containing audio loops from Apple. This source provides data when MLMediaLoadFoldersKey is provided with the MLMediaLoadAppleLoops value.

      Available in OS X v10.9 and later.

    • MLMediaSourceAppDefinedFoldersIdentifier

      MLMediaSourceAppDefinedFoldersIdentifier

      The media source for app-defined folders. This identifies a media source created from a relative path inside the caller’s app bundle. This source provides data when MLMediaLoadAppFoldersKey is provided in the options.

      Available in OS X v10.9 and later.

  • Identifiers for well-known media folders used to specify the value for MLMediaLoadFoldersKey.

    Declaration

    Swift

    let MLMediaLoadAppleLoops: NSString! let MLMediaLoadMoviesFolder: NSString!

    Objective-C

    NSString* const MLMediaLoadAppleLoops; NSString* const MLMediaLoadMoviesFolder;

    Constants

    • MLMediaLoadAppleLoops

      MLMediaLoadAppleLoops

      Identifies the folder containing audio loops from Apple.

      Available in OS X v10.9 and later.

    • MLMediaLoadMoviesFolder

      MLMediaLoadMoviesFolder

      Identifies the user’s Movies folder.

      Available in OS X v10.9 and later.