iOS Developer Library

Developer

MediaAccessibility Framework Reference Media Accessibility Function Reference

Options
Deployment Target:

On This Page
Language:

Media Accessibility Function Reference

The Media Accessibility caption functions provides access to user captioning preferences. Both iOS 7 and OS X 10.9 allow users to create custom styles for caption appearance. To understand the context of the Media Accessibility framework, you need to understand the available user settings. These options are provided in the Accessibility section of System Preferences application as shown in Figure 1. The settings affect attributes such as caption color, font, and language. Some of the options are shown in Figure 2. By choosing custom styles for media text, users are requesting improved legibility.

Figure 1Accessibility preferences pane in OS X image: ../Art/SystemPreferences_2x.png
Figure 2Caption appearance preferences pane in OS X image: ../Art/CaptionPreferences_2x.png

The Media Accessibility functions are provided for you to tailor the user experience of your media content. You must be able to influence the caption rendering process at time of delivery for the following functions to be useful. Retrieving the user's preferences and dynamically rendering the captions for maximum readability provides the best user experience.

Functions

  • Adds a preference for caption language to stack of languages.

    Declaration

    Swift

    func MACaptionAppearanceAddSelectedLanguage(_ domain: MACaptionAppearanceDomain, _ language: CFString!) -> Bool

    Objective-C

    bool MACaptionAppearanceAddSelectedLanguage ( MACaptionAppearanceDomain domain, CFStringRef language );

    Parameters

    domain

    The domain to retrieve the preference value from. See Caption Appearance Domains. Pass kMACaptionAppearanceDomainUser unless the system defaults are needed for comparison.

    language

    A canonical language identifier (see CFLocale Reference) of the preferred caption language.

    Return Value

    Returns true if addition was successful; false if an error occurred. Errors are most likely the result of invalid language codes.

    Discussion

    The added language will appear in the array returned by MACaptionAppearanceCopySelectedLanguages. Call the MACaptionAppearanceAddSelectedLanguage function anytime a user selects a specific captioning language from a pop-up menu or other UI affordance. For example, an AVFoundation client may execute the following code:

    • // in response to a user selection, make the selection effective
    • -[AVPlayerItem selectMediaOption:legibleOption inMediaSelectionGroup:legibleGroup];
    • // now update system-wide captioning preferences by registering the added language
    • MACaptionAppearanceAddSelectedLanguage(kMACaptionAppearanceDomainUser, (CFStringRef)[[legibleOption locale] localeIdentifier]);

    Import Statement

    import MediaAccessibility

    Availability

    Available in iOS 7.0 and later.

  • Returns the preferred caption languages.

    Declaration

    Swift

    func MACaptionAppearanceCopySelectedLanguages(_ domain: MACaptionAppearanceDomain) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef MACaptionAppearanceCopySelectedLanguages ( MACaptionAppearanceDomain domain );

    Parameters

    domain

    The domain to retrieve the preference value from. See Caption Appearance Domains. Pass kMACaptionAppearanceDomainUser unless the system defaults are needed for comparison.

    Return Value

    An ordered array of preferred canonical language identifiers.

    Discussion

    Languages added using the MACaptionAppearanceAddSelectedLanguage function are normalized. As a result, the contents of the returned array may have slightly different strings from those passed into MACaptionAppearanceAddSelectedLanguage.

    Import Statement

    import MediaAccessibility

    Availability

    Available in iOS 7.0 and later.

Constants

  • A value used to specify which domain a preference setting is retrieved from.

    Declaration

    Swift

    enum MACaptionAppearanceDomain : CFIndex { case Default case User }

    Objective-C

    typedef enum : CFIndex { kMACaptionAppearanceDomainDefault = 0, kMACaptionAppearanceDomainUser = 1, } MACaptionAppearanceDomain;

    Constants

    • Default

      kMACaptionAppearanceDomainDefault

      The system default value for the setting should be returned.

      Available in iOS 7.0 and later.

    • User

      kMACaptionAppearanceDomainUser

      The user's preferred value for the setting should be returned.

      Available in iOS 7.0 and later.

    Import Statement

    import MediaAccessibility

    Availability

    Available in iOS 7.0 and later.

  • A value used to specify the type of captions to be displayed.

    Declaration

    Swift

    enum MACaptionAppearanceDisplayType : CFIndex { case ForcedOnly case Automatic case AlwaysOn }

    Objective-C

    typedef enum : CFIndex { kMACaptionAppearanceDisplayTypeForcedOnly = 0, kMACaptionAppearanceDisplayTypeAutomatic = 1, kMACaptionAppearanceDisplayTypeAlwaysOn = 2, } MACaptionAppearanceDisplayType;

    Constants

    • ForcedOnly

      kMACaptionAppearanceDisplayTypeForcedOnly

      Do not display captions unless they are forced for translation.

      Available in iOS 7.0 and later.

    • Automatic

      kMACaptionAppearanceDisplayTypeAutomatic

      If the language of the audio track differs from the system locale, then captions matching the system locale should be displayed (if available). If the language of the audio and the language of the system locale match, no captions are shown.

      Available in iOS 7.0 and later.

    • AlwaysOn

      kMACaptionAppearanceDisplayTypeAlwaysOn

      The most robust available captioning track should always be displayed, whether subtitles, CC, or SDH. This option is selected by a switch labeled “Closed Captions + SDH” (on the Subtitles & Captioning page of iOS) and “Prefer Closed Captions and SDH” checkbox (on the Captions pane of the Accessibility options on OS X).

      Available in iOS 7.0 and later.

    Import Statement

    import MediaAccessibility

    Availability

    Available in iOS 7.0 and later.

  • A value used to indicate the preferred behavior for a preference setting.

    Declaration

    Swift

    enum MACaptionAppearanceBehavior : CFIndex { case UseValue case UseContentIfAvailable }

    Objective-C

    typedef enum : CFIndex { kMACaptionAppearanceBehaviorUseValue = 0, kMACaptionAppearanceBehaviorUseContentIfAvailable = 1, } MACaptionAppearanceBehavior;

    Constants

    • UseValue

      kMACaptionAppearanceBehaviorUseValue

      The preference setting should always be used.

      Available in iOS 7.0 and later.

    • UseContentIfAvailable

      kMACaptionAppearanceBehaviorUseContentIfAvailable

      The preference setting should be used unless the content media being played has its own custom value for this setting.

      Available in iOS 7.0 and later.

    Import Statement

    import MediaAccessibility

    Availability

    Available in iOS 7.0 and later.

  • A value used to specify a font style.

    Declaration

    Swift

    enum MACaptionAppearanceFontStyle : CFIndex { case Default case MonospacedWithSerif case ProportionalWithSerif case MonospacedWithoutSerif case ProportionalWithoutSerif case Casual case Cursive case SmallCapital }

    Objective-C

    typedef enum : CFIndex { kMACaptionAppearanceFontStyleDefault = 0, kMACaptionAppearanceFontStyleMonospacedWithSerif = 1, kMACaptionAppearanceFontStyleProportionalWithSerif = 2, kMACaptionAppearanceFontStyleMonospacedWithoutSerif = 3, kMACaptionAppearanceFontStyleProportionalWithoutSerif = 4, kMACaptionAppearanceFontStyleCasual = 5, kMACaptionAppearanceFontStyleCursive = 6, kMACaptionAppearanceFontStyleSmallCapital = 7, } MACaptionAppearanceFontStyle;

    Constants

    • Default

      kMACaptionAppearanceFontStyleDefault

      The default font style for all caption text.

      Available in iOS 7.0 and later.

    • MonospacedWithSerif

      kMACaptionAppearanceFontStyleMonospacedWithSerif

      The font style preferred for the monospaced serif font style.

      Available in iOS 7.0 and later.

    • ProportionalWithSerif

      kMACaptionAppearanceFontStyleProportionalWithSerif

      The font style preferred for the proportional serif font style.

      Available in iOS 7.0 and later.

    • MonospacedWithoutSerif

      kMACaptionAppearanceFontStyleMonospacedWithoutSerif

      The font style preferred for the monospaced sans serif font style.

      Available in iOS 7.0 and later.

    • ProportionalWithoutSerif

      kMACaptionAppearanceFontStyleProportionalWithoutSerif

      The font style preferred for the proportional sans serif font style.

      Available in iOS 7.0 and later.

    • Casual

      kMACaptionAppearanceFontStyleCasual

      The font style preferred for the casual font style.

      Available in iOS 7.0 and later.

    • Cursive

      kMACaptionAppearanceFontStyleCursive

      The font style preferred for the cursive font style.

      Available in iOS 7.0 and later.

    • SmallCapital

      kMACaptionAppearanceFontStyleSmallCapital

      The font style preferred for the small capital font style.

      Available in iOS 7.0 and later.

    Import Statement

    import MediaAccessibility

    Availability

    Available in iOS 7.0 and later.

  • A value used to specify detail added to the outside of the text.

    Declaration

    Swift

    enum MACaptionAppearanceTextEdgeStyle : CFIndex { case Undefined case None case Raised case Depressed case Uniform case DropShadow }

    Objective-C

    typedef enum : CFIndex {] kMACaptionAppearanceTextEdgeStyleUndefined = 0, ] kMACaptionAppearanceTextEdgeStyleNone = 1, kMACaptionAppearanceTextEdgeStyleRaised = 2, kMACaptionAppearanceTextEdgeStyleDepressed = 3, kMACaptionAppearanceTextEdgeStyleUniform = 4, kMACaptionAppearanceTextEdgeStyleDropShadow = 5, } MACaptionAppearanceTextEdgeStyle;

    Constants

    • Undefined

      kMACaptionAppearanceTextEdgeStyleUndefined

      An edge style has not been specified.

      Available in iOS 7.0 and later.

    • None

      kMACaptionAppearanceTextEdgeStyleNone

      The text should not have a styled edge.

      Available in iOS 7.0 and later.

    • Raised

      kMACaptionAppearanceTextEdgeStyleRaised

      An edge makes the text appear to rise above the background.

      Available in iOS 7.0 and later.

    • Depressed

      kMACaptionAppearanceTextEdgeStyleDepressed

      An edge makes the text appear pushed in.

      Available in iOS 7.0 and later.

    • Uniform

      kMACaptionAppearanceTextEdgeStyleUniform

      A thin outline lies along the edge of the text.

      Available in iOS 7.0 and later.

    • DropShadow

      kMACaptionAppearanceTextEdgeStyleDropShadow

      An edge makes the text appear to float above the background.

      Available in iOS 7.0 and later.

    Import Statement

    import MediaAccessibility

    Availability

    Available in iOS 7.0 and later.

  • A value used to indicate preferences for audio tracks.

    Declaration

    Swift

    let MAMediaCharacteristicDescribesMusicAndSoundForAccessibility: CFString! let MAMediaCharacteristicTranscribesSpokenDialogForAccessibility: CFString!

    Objective-C

    CFStringRef const MAMediaCharacteristicDescribesMusicAndSoundForAccessibility; CFStringRef const MAMediaCharacteristicTranscribesSpokenDialogForAccessibility;

    Constants

    • MAMediaCharacteristicDescribesMusicAndSoundForAccessibility

      MAMediaCharacteristicDescribesMusicAndSoundForAccessibility

      The user wants captions that describe music and sound (other than spoken dialog), such as sound effects and significant silences.

      Available in iOS 7.0 and later.

    • MAMediaCharacteristicTranscribesSpokenDialogForAccessibility

      MAMediaCharacteristicTranscribesSpokenDialogForAccessibility

      The user wants captions for spoken dialog. Captions should also identify speakers whenever other visual cues are insufficient for a viewer to determine who is speaking.

      Available in iOS 7.0 and later.

    Import Statement