Media Accessibility Function Reference

Framework
MediaAccessibility/MediaAccessibility.h
Declared in
MACaptionAppearance.h

Overview

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 1  Accessibility preferences pane in OS X
Figure 2  Caption appearance preferences pane in OS X

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 by Task

Accessing General Preferences

Accessing Language Preferences

Accessing Text Rendering Preferences

Accessing Text Highlight Preferences

Accessing Caption Window Preferences

Functions

MACaptionAppearanceAddSelectedLanguage

Adds a preference for caption language to stack of languages.

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]);
Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceCopyBackgroundColor

Returns the color of the preference for the text highlight.

CGColorRef MACaptionAppearanceCopyBackgroundColor (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceBehavior *behavior
);
Parameters
domain

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

behavior

A pointer to memory. On return, this memory holds the caption appearance behavior for this preference setting. For possible values see “Caption Appearance Behavior.” Pass NULL when you do not need the behavior setting.

Return Value

The preferred color shown behind the text and above the window color.

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceCopyFontDescriptorForStyle

Returns the preferred font for the specified style of type.

CTFontDescriptorRef MACaptionAppearanceCopyFontDescriptorForStyle (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceBehavior *behavior,
   MACaptionAppearanceFontStyle fontStyle
);
Parameters
domain

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

behavior

A pointer to memory. On return, this memory holds the caption appearance behavior for this preference setting. For possible values see “Caption Appearance Behavior.” Pass NULL when you do not need the behavior setting.

fontStyle

A font style, such as cursive or small caps, see “Caption Appearance Font Style.”

Return Value

The name of the preferred font for the specified style.

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceCopyForegroundColor

Returns the preference for text color.

CGColorRef MACaptionAppearanceCopyForegroundColor (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceBehavior *behavior
);
Parameters
domain

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

behavior

A pointer to memory. On return, this memory holds the caption appearance behavior for this preference setting. For possible values see “Caption Appearance Behavior.” Pass NULL when you do not need the behavior setting.

Return Value

The preferred color for caption text.

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceCopyPreferredCaptioningMediaCharacteristics

Returns the preferences for captioning sounds.

CFArrayRef MACaptionAppearanceCopyPreferredCaptioningMediaCharacteristics (
   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 array containing the preferred media characteristics for captioning of music, sounds, and dialog. See “Audio Track Characteristics.”

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceCopySelectedLanguages

Returns the preferred caption languages.

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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceCopyWindowColor

Returns the preference for the caption window’s color.

CGColorRef MACaptionAppearanceCopyWindowColor (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceBehavior *behavior
);
Parameters
domain

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

behavior

A pointer to memory. On return, this memory holds the caption appearance behavior for this preference setting. For possible values see “Caption Appearance Behavior.” Pass NULL when you do not need the behavior setting.

Return Value

The preferred color displayed behind all other caption elements.

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceGetBackgroundOpacity

Returns the preferred opacity for the text highlight.

CGFloat MACaptionAppearanceGetBackgroundOpacity (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceBehavior *behavior
);
Parameters
domain

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

behavior

A pointer to memory. On return, this memory holds the caption appearance behavior for this preference setting. For possible values see “Caption Appearance Behavior.” Pass NULL when you do not need the behavior setting.

Return Value

A float value, ranging from 0.0 to 1.0, representing the opacity of the color behind the text and above the window color.

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceGetDisplayType

Returns the preferred type of captions to be displayed.

MACaptionAppearanceDisplayType MACaptionAppearanceGetDisplayType (
   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

A value representing options to use only forced captions, allow system locale to override the language of the audio track, or choose the best available captioning track from CC, SDH, or subtitles. See “Caption Appearance Display Type.”

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceGetForegroundOpacity

Returns the preference for text opacity.

CGFloat MACaptionAppearanceGetForegroundOpacity (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceBehavior *behavior
);
Parameters
domain

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

behavior

A pointer to memory. On return, this memory holds the caption appearance behavior for this preference setting. For possible values see “Caption Appearance Behavior.” Pass NULL when you do not need the behavior setting.

Return Value

The float value, ranging from 0.0 to 1.0, representing the opacity of the color for text opacity.

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceGetRelativeCharacterSize

Returns the preference for font scaling.

CGFloat MACaptionAppearanceGetRelativeCharacterSize (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceBehavior *behavior
);
Parameters
domain

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

behavior

A pointer to memory. On return, this memory holds the caption appearance behavior for this preference setting. For possible values see “Caption Appearance Behavior.” Pass NULL when you do not need the behavior setting.

Return Value

The font scaling preference, as a multiplier, for the specified style; ranging from 0.0 to 2.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceGetTextEdgeStyle

Returns the preference for text edge style.

MACaptionAppearanceTextEdgeStyle MACaptionAppearanceGetTextEdgeStyle (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceBehavior *behavior
);
Parameters
domain

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

behavior

A pointer to memory. On return, this memory holds the caption appearance behavior for this preference setting. For possible values see “Caption Appearance Behavior.” Pass NULL when you do not need the behavior setting.

Return Value

The preferred text edge style, such as Raised or Drop Shadow. See “Caption Appearance Text Edge Style.”

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceGetWindowOpacity

Returns the preference for the overlay’s opacity.

CGFloat MACaptionAppearanceGetWindowOpacity (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceBehavior *behavior
);
Parameters
domain

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

behavior

A pointer to memory. On return, this memory holds the caption appearance behavior for this preference setting. For possible values see “Caption Appearance Behavior.” Pass NULL when you do not need the behavior setting.

Return Value

The float value, ranging from 0.0 to 1.0, representing the opacity of the color behind all other caption elements.

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceGetWindowRoundedCornerRadius

Returns the radius of the caption window’s corners.

CGFloat MACaptionAppearanceGetWindowRoundedCornerRadius (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceBehavior *behavior
);
Parameters
domain

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

behavior

A pointer to memory. On return, this memory holds the caption appearance behavior for this preference setting. For possible values see “Caption Appearance Behavior.” Pass NULL when you do not need the behavior setting.

Return Value

The system setting for the caption window’s corner radius.

Discussion

The rounded corners of the caption window are not customizable within the Accessibility preferences and do not change based on text size.

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

MACaptionAppearanceSetDisplayType

Sets the preference for the type of caption.

void MACaptionAppearanceSetDisplayType (
   MACaptionAppearanceDomain domain,
   MACaptionAppearanceDisplayType displayType
);
Parameters
domain

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

displayType

A value representing options to use only forced captions, to allow system locale to override the language of the audio track, or to choose the best available captioning track from CC, SDH, or subtitles. See “Caption Appearance Display Type.”

Availability
  • Available in iOS 7.0 and later.
Declared In
MACaptionAppearance.h

Constants

Caption Appearance Domains

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

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

The system default value for the setting should be returned.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceDomainUser

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

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

Caption Appearance Display Type

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

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

Do not display captions unless they are forced for translation.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

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.

Declared in MACaptionAppearance.h.

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.

Declared in MACaptionAppearance.h.

Caption Appearance Behavior

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

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

The preference setting should always be used.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

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.

Declared in MACaptionAppearance.h.

Caption Appearance Font Style

A value used to specify a font style.

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

The default font style for all caption text.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceFontStyleMonospacedWithSerif

The font style preferred for the monospaced serif font style.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceFontStyleProportionalWithSerif

The font style preferred for the proportional serif font style.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceFontStyleMonospacedWithoutSerif

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

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceFontStyleProportionalWithoutSerif

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

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceFontStyleCasual

The font style preferred for the casual font style.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceFontStyleCursive

The font style preferred for the cursive font style.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceFontStyleSmallCapital

The font style preferred for the small capital font style.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

Caption Appearance Text Edge Style

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

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

An edge style has not been specified.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceTextEdgeStyleNone

The text should not have a styled edge.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceTextEdgeStyleRaised

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

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceTextEdgeStyleDepressed

An edge makes the text appear pushed in.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceTextEdgeStyleUniform

A thin outline lies along the edge of the text.

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

kMACaptionAppearanceTextEdgeStyleDropShadow

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

Available in iOS 7.0 and later.

Declared in MACaptionAppearance.h.

Audio Track Characteristics

A value used to indicate preferences for audio tracks.

CFStringRef const MAMediaCharacteristicDescribesMusicAndSoundForAccessibility;
CFStringRef const MAMediaCharacteristicTranscribesSpokenDialogForAccessibility;
Constants
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.

Declared in MACaptionAppearance.h.

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.

Declared in MACaptionAppearance.h.