Repository navigation
PDF Spec 13 Multimedia
Part of: PDF-Spec-13-Multimedia-Features
Navigation: ← Previous | PDF-Spec-Index | PDF-Spec-13-Sounds
This clause describes those features of PDF that support embedding and playing multimedia content. It contains the following sub-clauses:
- 13.2, 'Multimedia,' describes the comprehensive set of multimedia capabilities that were introduced in PDF 1.5.
- 13.3, 'Sounds,' and 13.4, 'Movies,' describe features that have been supported since PDF 1.2.
- 13.5, 'Alternate Presentations,' describes a slideshow capability that was introduced in PDF 1.4.
- 13.6, '3D Artwork,' describes the capability of embedding three-dimensional graphics in a document, introduced in PDF 1.6.
PDF 1.5 introduces a comprehensive set of language constructs to enable the following capabilities:
- Arbitrary media types may be embedded in PDF files.
- Embedded media, as well as referenced media outside a PDF file, may be played with a variety of player software. (In some situations, the player software may be the conforming reader itself.)
NOTE 1 The term playing is used with a wide variety of media, and is not restricted to audio or video. For example, it may be applied to static images such as JPEGs.
- Media objects may have multiple renditions , which may be chosen at play-time based on considerations such as available bandwidth.
- Document authors may control play-time requirements, such as which player software should be used to play a given media object.
- Media objects may be played in various ways; for example, in a floating window as well as in a region on a page.
- Future extensions to the media constructs may be handled in an appropriate manner by current conforming readers. Authors may control how old conforming readers treat future extensions.
- Document authors may adapt the use of multimedia to accessibility requirements.
- On-line media objects may be played efficiently, even when very large.
The following list summarizes the multimedia features and indicates where each feature is discussed:
-
13.2.2, 'Viability,' describes the rules for determining when media objects are suitable for playing on a particular system.
-
Rendition actions (see 12.6.4.13, 'Rendition Actions') shall be used to begin the playing of multimedia content.
-
A rendition action associates a screen annotation (see 12.5.6.18, 'Screen Annotations') with a rendition (see 13.2.3, 'Renditions').
-
Renditions are of two varieties: media renditions (see 13.2.3.2, 'Media Renditions') that define the characteristics of the media to be played, and selector renditions (see 13.2.3.3, 'Selector Renditions') that enables choosing which of a set of media renditions should be played.
-
Media renditions contain entries that specify what should be played (see 13.2.4, 'Media Clip Objects'), how it should be played (see 13.2.5, 'Media Play Parameters'), and where it should be played (see 13.2.6, 'Media Screen Parameters').
-
13.2.7, 'Other Multimedia Objects,' describes several PDF objects that are referenced by the preceding major objects.
-
NOTE 2 Some of the features described in the following sub-clauses have references to corresponding elements in the Synchronized Multimedia Integration Language (SMIL 2.0) standard (see the Bibliography).
When playing multimedia content, the conforming reader shall often make decisions such as which player software and which options, such as volume and duration, to use.
In making these decisions, the viewer shall determine the viability of the objects used. If an object is considered non-viable, the media should not be played. If the object is viable, the media should be played, though possibly under less than optimum conditions.
There are several entries in the multimedia object dictionaries whose values shall have an effect on viability. In particular, some of the object dictionaries define two entries that divide options into one of two categories:
- MH ('must honour') : The options specified by this entry shall be honoured; otherwise, the containing object shall be considered non-viable.
- BE ('best effort '): An attempt should be made to honour the options; however, if they cannot be honoured, the containing object is still considered viable.
MH and BE are both dictionaries, and the same entries shall be defined for both of them. In any dictionary where these entries are allowed, both entries may be present, or only one, or neither.
EXAMPLE The media play parameters dictionary (see Table 279) allows the playback volume to be set by means of the V entry in its MH and BE dictionaries (see Table 280).
If the specified volume cannot be honoured, the object shall be considered non-viable if V is in the MH dictionary, and playback shall not occur. If V is in the BE dictionary (and not also in the MH dictionary), playback should still occur: the playing software attempts to honour the specified option as best it can.
Using this mechanism, authors may specify minimum requirements ( MH ) and preferred options ( BE ). They may also specify how entries that are added in the future to the multimedia dictionaries shall be interpreted by old conforming readers. If an entry that is unrecognized by the viewer is in the MH dictionary, the object shall be considered non-viable. If an unrecognized entry is in a BE dictionary, the entry shall be ignored and viability shall be unaffected. Unless otherwise stated, an object shall be considered non-viable if its MH dictionary contains an unrecognized key or an unrecognized value for a recognized key.
The following rules apply to the entries in MH and BE dictionaries, which behave somewhat differently from other PDF dictionaries:
-
If an entry is required, the requirement is met if the entry is present in either the MH dictionary or the BE dictionary.
-
If an optional entry is not present in either dictionary, it shall be considered to be present with its default value (if one is defined) in the BE dictionary.
-
If an instance of the same entry is present in both MH and BE , the instance in the BE dictionary shall be ignored unless otherwise specified.
-
If the value of an entry in an MH or a BE dictionary is a dictionary or array, it shall be treated as an atomic unit when determining viability. That is, all entries within the dictionary or array shall be honoured for the containing object to be viable.
-
NOTE When determining whether entries can be honoured, it is not required that each one be evaluated independently, since they may be dependent on one another. That is, a conforming reader or player may examine multiple entries at once (even within different dictionaries) to determine whether their values can be honoured.
The following media objects may have MH and BE dictionaries. They function as described previously, except where noted in the individual sub-clauses:
- Rendition (Table 267)
- Media clip data (Table 276)
- Media clip section (Table 278)
- Media play parameters (Table 280)
- Media screen parameters (Table 283)
There are two types of rendition objects:
- A media rendition (see 13.2.3.2, 'Media Renditions') is a basic media object that specifies what to play, how to play it, and where to play it.
- A selector rendition (see 13.2.3.3, 'Selector Renditions') contains an ordered list of renditions. This list may include other selector renditions, resulting in a tree whose leaves are media renditions. The conforming reader should play the first viable media rendition it encounters in the tree (see 13.2.2, 'Viability').
- NOTE 1 Table 266 shows the entries common to all rendition dictionaries. The N entry in a rendition dictionary specifies a name that can be used to access the rendition object by means of name tree lookup (see Table 31). JavaScript actions (see 12.6.4.16, 'JavaScript Actions'), for example, use this mechanism.
Since the values referenced by name trees shall be indirect objects, all rendition objects should be indirect objects.
- NOTE 2 A rendition dictionary is not required to have a name tree entry. When it does, the conforming reader should ensure that the name specified in the tree is kept the same as the value of the N entry (for example, if the user interface allows the name to be changed). A document should not contain multiple renditions with the same name.
The MH and BE entries are dictionaries whose entries may be present in one or the other of them, as described in 13.2.2, 'Viability.' For renditions, these dictionaries shall have a single entry C (see Table 267), whose value shall have a media criteria dictionary specifying a set of criteria that shall be met for the rendition to be considered viable (see Table 268).
The media criteria dictionary behaves somewhat differently than other MH / BE entries, as they are described in 13.2.2, 'Viability.' The criteria specified by all of its entries shall be met regardless of whether they are in an MH or a BE dictionary. The only exception is that if an entry in a BE dictionary is unrecognized by the conforming
reader, it shall not affect the viability of the object. If a media criteria dictionary is present in both MH and BE , the entries in both dictionaries shall be individually evaluated, with MH taking precedence (corresponding BE entries shall be ignored).
Table 266 - Entries common to all rendition dictionaries
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that dictionary describes; if present, shall be Rendition for a rendition object. |
| S | name | (Required) The type of rendition that this dictionary describes. May be MR for media rendition or SR for selector rendition. The rendition shall be considered non-viable if the conforming reader does not recognize the value of this entry. |
| N | text string | (Optional) A Unicode-encoded text string specifying the name of the rendition for use in a user interface and for name tree lookup by JavaScript actions. |
| MH | dictionary | (Optional) A dictionary whose entries (see Table 267) shall be honoured for the rendition to be considered viable. |
| BE | dictionary | (Optional) A dictionary whose entries (see Table 267) shall only be honoured in a 'best effort' sense. |
Table 267 - Entries in a rendition MH/BE dictionary
| Key | Type | Value |
|---|---|---|
| C | dictionary | (Optional) A media criteria dictionary (see Table 268). The media criteria dictionary behaves somewhat differently than other MH / BE entries described in 13.2.2, 'Viability.' The criteria specified by all of its entries shall be met regardless of whether it is in an MH or a BE dictionary. The only exception is that if an entry in a BE dictionary is unrecognized by the conforming reader, it shall not affect the viability of the object. |
Table 268 - Entries in a media criteria dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be MediaCriteria for a media criteria dictionary. |
| A | boolean | (Optional) If specified, the value of this entry shall match the user's preference for whether to hear audio descriptions in order for this object to be viable. NOTE 1 Equivalent to SMIL's systemAudioDesc attribute. |
| C | boolean | (Optional) If specified, the value of this entry shall match the user's preference for whether to see text captions in order for this object to be viable. NOTE 2 Equivalent to SMIL's systemCaptions attribute. |
| O | boolean | (Optional) If specified, the value of this entry shall match the user's preference for whether to hear audio overdubs in order for this object to be viable. |
| S | boolean | (Optional) If specified, the value of this entry shall match the user's preference for whether to see subtitles in order for this object to be viable. |
Table 268 - Entries in a media criteria dictionary (continued)
| Key | Type | Value |
|---|---|---|
| R | integer | (Optional) If specified, the system's bandwidth (in bits per second) shall be greater than or equal to the value of this entry in order for this object to be viable. NOTE 3 Equivalent to SMIL's systemBitrate attribute. |
| D | dictionary | (Optional) A dictionary (see Table 269) specifying the minimum bit depth required in order for this object to be viable. NOTE 4 Equivalent to SMIL's systemScreenDepth attribute. |
| Z | dictionary | (Optional) A dictionary (see Table 270) specifying the minimum screen size required in order for this object to be viable. NOTE 5 Equivalent to SMIL's systemScreenSize attribute. |
| V | array | (Optional) An array of software identifier objects (see 13.2.7.4, 'Software Identifier Dictionary'). If this entry is present and non-empty, the conforming reader shall be identified by one or more of the objects in the array in order for this object to be viable. |
| P | array | (Optional) An array containing one or two name objects specifying a minimum and optionally a maximum PDF language version, in the same format as the Version entry in the document catalog (see Table 28). If this entry is present and non-empty, the version of multimedia constructs fully supported by the conforming reader shall be within the specified range in order for this object to be viable. |
| L | array | (Optional) An array of language identifiers (see 14.9.2.2, 'Language Identifiers'). If this entry is present and non-empty, the language in which the conforming reader is running shall exactly match a language identifier, or consist only of a primary code that matches the primary code of an identifier, in order for this object to be viable. NOTE 6 Equivalent to SMIL's systemLanguage attribute. |
Table 269 - Entries in a minimum bit depth dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be MinBitDepth for a minimum bit depth dictionary. |
| V | integer | (Required) A positive integer (0 or greater) specifying the minimum screen depth (in bits) of the monitor for the rendition to be viable. A negative value shall not be allowed. |
| M | integer | (Optional) A monitor specifier (see Table 270) that specifies which monitor the value of V should be tested against. If the value is unrecognized, the object shall not be viable. Default value: 0. |
Table 270 - Entries in a minimum screen size dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be MinScreenSize for a rendition object. |
| V | array | (Required) An array containing two non-negative integers. The width and height (in pixels) of the monitor specified by M shall be greater than or equal to the values of the first and second integers in the array, respectively, in order for this object to be viable. |
| M | integer | (Optional) A monitor specifier (see Table 293) that specifies which monitor the value of V should be tested against. If the value is unrecognized, the object shall be not viable. Default value: 0. |
Table 271 lists the entries in a media rendition dictionary. Its entries specify what media should be played ( C ), how ( P ), and where ( SP ) it should be played. A media rendition object shall be viable if and only if the objects referenced by its C , P , and SP entries are viable.
C may be omitted only in cases where a referenced player takes no meaningful input. This requires that P shall be present and that its referenced media play parameters dictionary (see Table 279) shall contain a PL entry, whose referenced media players dictionary (see 13.2.7.2, 'Media Players Dictionary') has a non-empty MU array or a non-empty A array.
Table 271 - Additional entries in a media rendition dictionary
| Key | Type | Value |
|---|---|---|
| C | dictionary | (Optional) A media clip dictionary (see 13.2.4, 'Media Clip Objects') that specifies what should be played when the media rendition object is played. |
| P | dictionary | (Required if C is not present, otherwise optional) A media play parameters dictionary (see 13.2.5, 'Media Play Parameters'') that specifies how the media rendition object should be played. Default value: a media play parameters dictionary whose entries (see Table 279) all contain their default values. |
| SP | dictionary | (Optional) A media screen parameters dictionary (see 13.2.6, 'Media Screen Parameters') that specifies where the media rendition object should be played. Default value: a media screen parameters dictionary whose entries (see Table 282) all contain their default values. |
A selector rendition dictionary shall specify an array of rendition objects in its R entry (see Table 272). The renditions in this array should be ordered by preference, with the most preferred rendition first. At play-time, the renditions in the array shall be evaluated and the first viable media rendition, if any, shall be played. If one of the renditions is itself a selector, that selector shall be evaluated in turn, yielding the equivalent of a depth-first tree search. A selector rendition itself may be non-viable; in this case, none of its associated media renditions shall be evaluated (in effect, this branch of the tree is skipped).
NOTE This mechanism may be used, for example, to specify that a large video clip should be used on highbandwidth machines and a smaller clip should be used on low-bandwidth machines.
Table 272 - Additional entries specific to a selector rendition dictionary
| Key | Type | Value |
|---|---|---|
| R | array | (Required) An array of rendition objects. The first viable media rendition object found in the array, or nested within a selector rendition in the array, should be used. An empty array is legal. |
There are two types of media clip objects, determined by the subtype S , which can be either MCD for media clip data (see 13.2.4.2, 'Media Clip Data') or MCS for media clip section (see 13.2.4.3, 'Media Clip Section'). The entries common to all media clip dictionaries are listed in Table 273.
Table 273 - Entries common to all media clip dictionaries
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be MediaClip for a media clip dictionary. |
| S | name | (Required) The subtype of media clip that this dictionary describes. May be MCD for media clip data (see 13.2.4.2, 'Media Clip Data') or MCS for a media clip section (see 13.2.4.3, 'Media Clip Section'). The media clip shall be considered non-viable if the conforming reader does not recognize the value of this entry. |
| N | text string | (Optional) The name of the media clip, for use in the user interface. |
A media clip data dictionary defines the data for a media object that can be played. Its entries are listed in Table 274
NOTE 1 It may reference a URL to a streaming video presentation or a movie embedded in the PDF file.
Table 274 - Additional entries in a media clip data dictionary
| Key | Type | Value |
|---|---|---|
| D | file specification or stream | (Required) A full file specification or form XObject that specifies the actual media data. |
| CT | ASCII string | (Optional; not allowed for form XObjects) An ASCII string identifying the type of data in D . The string should conform to the content type specification described in Internet RFC 2045, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies (see the Bibliography). |
| P | dictionary | (Optional) A media permissions dictionary (see Table 275) containing permissions that control the use of the media data. Default value: a media permissions dictionary containing default values. |
| Alt | array | (Optional) An array that provides alternate text descriptions for the media clip data in case it cannot be played; see 14.9.2.4, 'Multi-language Text Arrays.' |
Table 274 - Additional entries in a media clip data dictionary (continued)
| Key | Type | Value |
|---|---|---|
| PL | dictionary | (Optional) A media players dictionary (see 13.2.7.2, 'Media Players Dictionary') that identifies, among other things, players that are legal and not legal for playing the media. If the media players dictionary is non-viable, the media clip data shall be non-viable. |
| MH | dictionary | (Optional) A dictionary whose entries (see Table 276) shall be honoured for the media clip data to be considered viable. |
| BE | dictionary | (Optional) A dictionary whose entries (see Table 276) should only be honoured in a 'best effort' sense. |
The media clip data object shall be considered non-viable if the object referenced by the D entry does not contain a Type entry, the Type entry is unrecognized, or the referenced object is not a dictionary or stream.
This shall effectively exclude the use of simple file specifications (see 7.11, 'File Specifications').
If D references a file specification that has an embedded file stream (see 7.11.4, 'Embedded File Streams'), the embedded file stream's Subtype entry shall be ignored if present, and the media clip data dictionary's CT entry shall identify the type of data.
If D references a form XObject, the associated player is implicitly the conforming reader, and the form XObject shall be rendered as if it were any other data type.
NOTE 2 The F and D entries in the media play parameters dictionary (see Table 279) should apply to a form XObject just as they do to a QuickTime movie.
For media other than form XObjects, the media clip object shall provide enough information to allow a conforming reader to locate an appropriate player. This may be done by providing one or both of the following entries, the first being the preferred method:
- A CT entry that specifies the content type of the media. If this entry is present, any player that is selected shall support this content type.
- A PL entry that specifies one or more players that may be used to play the referenced media. if CT is present, there should also be a PL present.
The P entry specifies a media permissions dictionary (see Table 275) specifying the manner in which the data referenced by the media may be used by a conforming reader. These permissions allow authors control over how their data is exposed to operations that could allow it to be copied. If the dictionary contains unrecognized entries or entries with unrecognized values, it shall be considered non-viable, and the conforming reader shall not play the media.
Table 275 - Entries in a media permissions dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be MediaPermissions for a media permissions dictionary. |
| TF | ASCII string | (Optional) An ASCII string indicating the circumstances under which it is acceptable to write a temporary file in order to play a media clip. Valid values are: (TEMPNEVER) Never allowed. (TEMPEXTRACT) Allowed only if the document permissions allow content extraction; when bit 5 of the user access permissions (see Table 22) is set. (TEMPACCESS) Allowed only if the document permissions allow content extraction, including for accessibility purposes; when bits 5 or 10 of the user access permissions (see Table 22) are set, or both. (TEMPALWAYS) Always allowed. Default value: (TEMPNEVER). An unrecognized value shall be treated as (TEMPNEVER). |
The BU entry in the media clip data MH and BE dictionaries (see Table 276) specifies a base URL for the media data. Relative URLs in the media (which point to auxiliary files or are used for hyperlinking) should be resolved with respect to the value of BU . The following are additional requirements concerning the BU entry:
- If BU is in the MH dictionary and the base URL is not honoured the media clip data shall be non-viable.
NOTE 3 An example of this is that the player does not accept base URLs.
- Determining the viability of the object shall not require checking whether the base URL is valid
NOTE 4 The target host exists.
- Absolute URls within the media shall not be affected.
- If the media itself contains a base URL, that value shall be used in preference to BU .
NOTE 5 An example of this is that the <BASE> element is defined in HTML.
- BU is completely independent of and unrelated to the value of the URI entry in the document catalogue (see 7.7.2, 'Document Catalog').
- If BU is not present and the media is embedded within the document, the URL to the PDF file itself shall be used as if it were the value of a BU entry in the BE dictionary; that is, as an implicit best-effort base URL.
Table 276 - Entries in a media clip data MH/BE dictionary
| Key | Type | Value |
|---|---|---|
| BU | ASCII string | (Optional) An absolute URL that shall be used as the base URL in resolving any relative URLs found within the media data. |
A media clip section dictionary (see Table 277) defines a continuous section of another media clip object (known as the next-level media clip object). The next-level media clip object, specified by the D entry, may be either a media clip data object or another media clip section object. However, the linked list formed by the D
entries of media clip sections shall terminate in a media clip data object. If the next-level media object is nonviable, the media clip section shall be also non-viable.
- NOTE 1 A media clip section could define a 15-minute segment of a media clip data object representing a two-hour movie.
Table 277 - Additional entries in a media clip section dictionary
| Key | Type | Value |
|---|---|---|
| D | dictionary | (Required) The media clip section or media clip data object (the next-level media object) of which this media clip section object defines a continuous section. |
| Alt | array | (Optional) An array that provides alternate text descriptions for the media clip section in case it cannot be played; see 14.9.2.4, 'Multi-language Text Arrays.' |
| MH | dictionary | (Optional) A dictionary whose entries (see Table 278) shall be honoured for the media clip section to be considered viable. |
| BE | dictionary | (Optional) A dictionary whose entries (see Table 278) shall only be honoured in a 'best effort' sense. |
The B and E entries in the media clip section's MH and BE dictionaries (see Table 278) shall define a subsection of the next-level media object referenced by D by specifying beginning and ending offsets into it. Depending on the media type, the offsets may be specified by time, frames, or markers (see 13.2.6.2, 'Media Offset Dictionary'). B and E are not required to specify the same type of offset.
The following rules apply to these offsets:
- For media types where an offset makes no sense (such as JPEG images), B and E shall be ignored, with no effect on viability.
- When B or E are specified by time or frames, their value shall be considered to be relative to the start of the next-level media clip. However, if E specifies an offset beyond the end of the next-level media clip, the end value shall be used instead, and there is no effect on viability.
- When B or E are specified by markers, there shall be a corresponding absolute offset into the underlying media clip data object. If this offset is not within the range defined by the next-level media clip (if any), or if the marker is not present in the underlying media clip, the existence of the entry shall be ignored, and there is no effect on viability.
- If the absolute offset derived from the values of all B entries in a media clip section chain is greater than or equal to the absolute offset derived from the values of all E entries, an empty range shall be defined. An empty range is legal.
- Any B or E entry in a media clip section's MH dictionary shall be honoured at play-time in order for the media clip section to be considered viable.
NOTE 2 The entry may not be honored if its value was not viable or if the player did not support its value; for example, the player did not support markers.
- If a B or E entry is in a media clip section's MH dictionary, all B or E entries, respectively, at deeper levels (closer to the media clip data), shall be evaluated as if they were in an MH dictionary (even if they are actually within BE dictionaries).
- If B or E entry in a BE dictionary cannot be supported, it may be ignored at play-time.
Table 278 - Entries in a media clip section MH/BE dictionary
| Key | Type | Value |
|---|---|---|
| B | dictionary | (Optional) A media offset dictionary (see 13.2.6.2, 'Media Offset Dictionary') that specifies the offset into the next-level media object at which the media clip section begins. Default: the start of the next-level media object. |
| E | dictionary | (Optional) A media offset dictionary (see 13.2.6.2, 'Media Offset Dictionary') that specifies the offset into the next-level media object at which the media clip section ends. Default: the end of the next-level media object. |
A media play parameters dictionary specifies how a media object should be played. It shall be referenced from a media rendition (see 13.2.3.2, 'Media Renditions').
Table 279 - Entries in a media play parameters dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be MediaPlayParams for a media play parameters dictionary. |
| PL | dictionary | (Optional) A media players dictionary (see 13.2.7.2, 'Media Players Dictionary') that identifies, among other things, players that are legal and not legal for playing the media. If this object is non-viable, the media play parameters dictionary shall be considered non-viable. |
| MH | dictionary | (Optional) A dictionary whose entries (see Table 278) shall be honoured for the media play parameters to be considered viable. |
| BE | dictionary | (Optional) A dictionary whose entries (see Table 278) shall only be honoured in a 'best effort' sense. |
Table 280 - Entries in a media play parameters MH/BE dictionary
| Key | Type | Value |
|---|---|---|
| V | integer | (Optional) An integer that specifies the desired volume level as a percentage of recorded volume level. A zero value shall be equivalent to mute; negative values shall be illegal. Default value: 100. |
| C | boolean | (Optional) A flag specifying whether to display a player-specific controller user interface when playing. EXAMPLE play/pause/stop controls. Default value: false |
Table 280 - Entries in a media play parameters MH/BE dictionary (continued)
| Key | Type | Value |
|---|---|---|
| F | integer' | (Optional) The manner in which the player shall treat a visual media type that does not exactly fit the rectangle in which it plays. 0The media's width and height shall be scaled while preserving the aspect ratio so that the media and play rectangles have the greatest possible intersection while still displaying all media content. NOTE 1 Same as 'meet' value of SMIL's fit attribute. 1 The media's width and height shall be scaled while preserving the aspect ratio so that the play rectangle is entirely filled, and the amount of media content that does not fit within the play rectangle shall be minimized. NOTE 2 Same as 'slice' value of SMIL's fit attribute. 2 The media's width and height shall be scaled independently so that the media and play rectangles are the same; the aspect ratio shall not be preserved. NOTE 3 Same as 'fill' value of SMIL's fit attribute. 3 The media shall not be scaled. A scrolling user interface shall be provided if the media rectangle is wider or taller than the play rectangle. NOTE 4 Same as 'scroll' value of SMIL's fit attribute. 4 The media shall not be scaled. Only the portions of the media rectangle that intersect the play rectangle shall be displayed. NOTE 5 Same as 'hidden' value of SMIL's fit attribute. 5 Use the player's default setting (author has no preference). Default value: 5. An unrecognized value shall be treated as the default value if the entry is in a BE dictionary. If the entry is in an MH dictionary and it has an unrecognized |
| D | dictionary | (Optional) A media duration dictionary (see Table 281). Default value: a dictionary specifying the intrinsic duration (see RC ). |
| A | boolean | (Optional) If true , the media shall automatically play when activated. If false , the media shall be initially paused when activated. EXAMPLE The first frame is displayed. Relevant only for media that may be paused. Default value: true . |
| RC | number | (Optional) Specifies the number of iterations of the duration D to repeat. NOTE 6 Similar to SMIL's repeatCount attribute. Zero means repeat forever. Negative values shall be illegal; non-integral values shall be legal. Default value: 1.0. |
The value of the D entry is a media duration dictionary , whose entries are shown in Table 281. It specifies a temporal duration.
NOTE 1 The D entry dictionary temporal duration corresponds to the notion of a simple duration in SMIL.
The duration may be a specific amount of time, it may be infinity, or it may be the media's intrinsic duration.
EXAMPLE The intrinsic duration of a two-hour QuickTime movie is two hours.
The intrinsic duration may be modified when a media clip section (see 13.2.4.3, 'Media Clip Section') is used: the intrinsic duration shall be the difference between the absolute begin and end offsets. For a media type having no notion of time (such as a JPEG image), the duration shall be considered to be infinity.
If the simple duration is longer than the intrinsic duration, the player shall freeze the media in its final state until the simple duration has elapsed. For visual media types, the last appearance (frame) shall be displayed. For aural media types, the media is logically frozen but shall not continue to produce sound.
- NOTE 2 In this case, the RC entry, which specifies a repeat count, applies to the simple duration; therefore, the entire play-pause sequence is repeated RC times.
Table 281 - Entries in a media duration dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be MediaDuration for a media duration dictionary. |
| S | name | (Required) The subtype of media duration dictionary. Valid values are: I The duration is the intrinsic duration of the associated media F The duration is infinity T The duration shall be specified by the T entry The media duration dictionary shall be considered non-viable if the conforming reader does not recognize the value of this entry. |
| T | dictionary | (Required if the value of S is T ; otherwise ignored) A timespan dictionary specifying an explicit duration (see Table 289). A negative duration is illegal. |
A media screen parameters dictionary (see Table 282) shall specify where a media object should be played. It shall contain MH and BE dictionaries (see Table 283), which shall function as discussed in 13.2.2, 'Viability.' All media clips that are being played shall be associated with a particular document and shall be stopped when the document is closed.
- NOTE Conforming readers should disallow floating windows and full-screen windows unless specifically allowed by the user. The reason is that document-based security attacks are possible if windows containing arbitrary media content can be displayed without indicating to the user that the window is merely hosting a media object. This recommendation may be relaxed if it is possible to communicate the nature of such windows to the user; for example, with text in a floating window's title bar.
Table 282 - Entries in a media screen parameters dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be MediaScreenParams for a media screen parameters dictionary. |
| MH | dictionary | (Optional) A dictionary whose entries (see Table 283) shall be honoured for the media screen parameters to be considered viable. |
| BE | dictionary | (Optional) A dictionary whose entries (see Table 283) should be honoured. |
Table 283 - Entries in a media screen parameters MH/BE dictionary
| Key | Type | Value |
|---|---|---|
| W | integer | (Optional) The type of window that the media object shall play in: 0 A floating window 1 A full-screen window that obscures all other windows 2 A hidden window 3 The rectangle occupied by the screen annotation (see 12.5.6.18, 'Screen Annotations') associated with the media rendition Default value: 3. Unrecognized value in MH : object is non-viable; in BE : treat as default value. |
| B | array | (Optional) An array of three numbers in the range 0.0 to 1.0 that shall specify the components in the DeviceRGB colour space of the background colour for the rectangle in which the media is being played. This colour shall be used if the media object does not entirely cover the rectangle or if it has transparent sections. It shall be ignored for hidden windows. Default value: implementation-defined. The conforming reader should choose a reasonable value based on the value of W . EXAMPLE 1 A system default background colour for floating windows or a user-preferred background colour for full-screen windows. If a media format has an intrinsic background colour, B shall not override it. However, the B colour shall be visible if the media has transparent areas or otherwise does not cover the entire window. |
| O | number | (Optional) A number in the range 0.0 to 1.0 specifying the constant opacity value that shall be used in painting the background colour specified by B . A value below 1.0 means the window shall be transparent. EXAMPLE 2 Windows behind a floating window show through if the media does not cover the entire floating window. A value of 0.0 shall indicate full transparency and shall make B irrelevant. It shall be ignored for full-screen and hidden windows. Default value: 1.0 (fully opaque). |
| M | integer | (Optional) A monitor specifier (see Table 293) that shall specify which monitor in a multi-monitor system, a floating or full-screen window shall appear on. Ignored for other types. Default value: 0 (document monitor). Unrecognized value in MH : object is non-viable; in BE : treat as default value. |
| F | dictionary | (Required if the value of W is 0; otherwise ignored) A floating window parameters dictionary (see Table 284) that shall specify the size, position, and options used in displaying floating windows. |
The F entry in the media screen parameters MH / BE dictionaries shall be a floating window parameters dictionary, whose entries are listed in Table 284. The entries in the floating window parameters dictionary shall be treated as if they were present in the MH or BE dictionaries that they are referenced from. That is, the contained entries shall be individually evaluated for viability rather than the dictionary being evaluated as a whole. (There may be an F entry in both MH and BE . In such a case, if a given entry is present in both floating window parameters dictionaries, the one in the MH dictionary shall take precedence.)
The D , P , and RT entries shall be used to specify the rectangle that the floating window occupies. Once created, the floating window's size and position shall not be tied to any other window, even if the initial size or position was computed relative to other windows.
Unrecognized values for the R , P , RT , and O entries shall be handled as follows: if they are nested within an MH dictionary, the floating window parameters object (and hence the media screen parameters object) shall be
considered non-viable; if they are nested within a BE dictionary, they shall be considered to have their default values.
Table 284 - Entries in a floating window parameters dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be FWParams for a floating window parameters dictionary. |
| D | array | (Required) An array containing two non-negative integers that shall represent the floating window's width and height, in pixels, respectively. These values shall correspond to the dimensions of the rectangle in which the media shall play, not including such items as title bar and resizing handles. |
| RT | integer | (Optional) The window relative to which the floating window shall be positioned: 0 The document window 1 The application window 2 The full virtual desktop 3 The monitor specified by M in the media screen parameters MH or BE dictionary (see 9.22) Default value: 0. |
| P | integer | (Optional) The location where the floating window (including such items as title bar and resizing handles) shall be positioned relative to the window specified by RT : 0 Upper-left corner 1 Upper center 2 Upper-right corner 3 Center left 4 Center 5 Center right 6 Lower-left corner 7 Lower center 8 Lower-right corner |
| O | integer | (Optional) Specifies what shall occur if the floating window is positioned totally or partially offscreen (that is, not visible on any physical monitor): 0 Take no special action 1 Move and/or resize the window so that it is on-screen 2 Consider the object to be non-viable Default value: 1 |
Navigation: ← Previous | PDF-Spec-Index | PDF-Spec-13-Sounds