data-id=media-and-marker-apis

data-id=id1

Media and Marker APIs

data-id=marker

data-id=id2

Marker

A Marker object represents a named location in a media clip that identifies a particular time or frame number, similar to a track on an audio CD or a chapter on a DVD. Markers are defined by the media clip itself.

A Marker object can be obtained from the Markers.get method.

data-id=marker-properties

data-id=id3

Marker properties

data-id=42227

data-id=frame

data-id=id4

frame

A frame number, where 0 represents the beginning of media. For most players, markers have either a frame or a time value, but not both.

data-id=90667

data-id=index

data-id=id5

index

An index number assigned to this marker. Markers have sequential index numbers beginning with 0, but the numbers may not be in the same order that the markers appear in the media.

data-id=81053

data-id=name

data-id=id6

name

The name of this marker. Each marker in a media clip has a unique name.

Example: Get a marker by its index, then print the name of the marker to the console.

// Assume player is a MediaPlayer object
var markers = player.markers;
// Get marker with index of 2
var markers = g.get( { index: 2 } );
console.println( "The marker with index of " + markers.index
    +", has a name of " + index.name );

data-id=55620

data-id=time

data-id=id7

time

A time in seconds, where 0 represents the beginning of media. For most players, markers have either a frame or a time value, but not both.

Example: Get a named marker, then print the time in seconds from the beginning of the media, of that marker.

// Assume player is a MediaPlayer object
var g = player.markers;
// Get marker with name of "Chapter 1"
var markers = g.get( { name: "Chapter 1" } );
console.println( "The named marker "Chapter 1", occurs at time "
    + markers.time);

data-id=46714

data-id=markers

data-id=id8

Markers

The markers property of a MediaPlayer is a Markers object that represents all of the markers found in the media clip currently loaded into the player. A marker is a named location in a media clip that identifies a particular time or frame number, similar to a track on an audio CD or a chapter on a DVD. Markers are defined by the media clip.

The constructor is app.media.Markers.

data-id=markers-properties

data-id=id9

Markers properties

data-id=49163

data-id=player

data-id=id10

player

The MediaPlayer object that this Markers object belongs to.

data-id=markers-methods

data-id=id11

Markers methods

• get

data-id=15049

data-id=get

data-id=id12

get

Looks up a marker by name, index number, time in seconds, or frame number and returns the Marker object representing the requested marker. The object parameter should contain either a name, index, time, or frame property. A marker name can also be passed in directly as a string.

If a time or frame is passed in, the nearest marker at or before that time or frame is returned. If the time or frame is before any markers in the media, null is returned.

Parameters

An object or string representing the name, index number, time in seconds, or the frame number of the marker. The object parameter should contain either a name, index, time, or frame property. A marker name can also be passed in directly as a string.

Returns

Marker object or null

Marker index numbers are assigned sequentially starting with 0. They are not necessarily in order by time or frame. In particular, note that these are not the same values that Windows Media Player uses for marker numbers. To find all of the available markers in a media clip, call MediaPlayer.markers.get in a loop starting with {index: 0} and incrementing the number until get returns null.

Example 1: Count the number of markers on the media clip.

var index, i =  0;
// assume player is a MediaPlayer object.
var m = player.markers;
while ( (index = m.get( { index: i } ) ) != null ) i++;
console.println("There are " + i + " markers.");

Example 2: Get markers by name, index, time and frame.

// Get a marker by name, two different ways
var marker = player.markers.get( "My Marker" );
var marker = player.markers.get({ name: "My Marker" });
// Get a marker by index
var marker = player.markers.get({ index: 1 });
// Get a marker by time
var marker = player.markers.get({ time: 17.5 });
// Get a marker by frame
var marker = player.markers.get({ frame: 43 });

data-id=40623

data-id=mediaoffset

data-id=id13

MediaOffset

A MediaOffset represents a position in a MediaClip, specified by time or frame count. The position can be absolute (that is, relative to the beginning of the media) or relative to a named marker.

The MediaOffset object can have the properties specified below, or it can simply be a number, which is interpreted as {time: number}.

Some media formats (such as QuickTime) are time-based and others (such as Flash) are frame-based. A MediaOffset that specifies a time or frame must match the media format in use. If both time and frame are specified, the results are undefined. The incorrect one may be ignored, or a JavaScript exception may be thrown.

The MediaOffset object is used by MediaPlayer. seek, MediaPlayer. where, MediaSettings. endAt, and MediaSettings. startAt.

data-id=mediaoffset-properties

data-id=id14

MediaOffset properties

data-id=85689

data-id=id15

frame

A frame number. If the marker property is also present, this frame number is relative to the specified marker and may be positive, negative, or zero. Otherwise, it is relative to the beginning of media and may not be negative. Note that {frame: 0} represents the beginning of media.

data-id=36461

data-id=id16

data-id=id17

marker

The name of a specific marker in the media.

data-id=66128

data-id=id18

data-id=id19

time

A time in seconds, or Infinity. If the marker property is also present, this time is relative to the specified marker and is a nonnegative value, but not Infinity. Otherwise, the time is relative to the beginning of media and must not be negative. Note that the offset { time: 0 } represents the beginning of media.

Example: These are examples of absolute and relative offsets.

{ time: 5.4 } // offset 5.4 seconds from the beginning of media
{ marker: "Chapter 1", time: 17 } // 17 seconds after "Chapter 1"

These offsets can be used by the MediaPlayer. seek method.

// assume player is a MediaPlayer object
player.seek({ time: 5.4 });
player.seek({ marker: "Chapter 1", time: 17 });

data-id=47696

data-id=mediaplayer

data-id=id20

MediaPlayer

A MediaPlayer object represents an instance of a multimedia player such as QuickTime, Windows Media Player, or others. Its settings and events properties let you manipulate the player from JavaScript code and handle events that the player triggers. MediaPlayer is not part of a PDF file; it is a transient object created in memory when needed.

data-id=mediaplayer-properties

data-id=id21

MediaPlayer properties

data-id=17383

data-id=annot

data-id=id22

annot

A reference to the screen annotation associated with a MediaPlayer. This property exists only for a MediaPlayer object that is connected to a screen annotation. The property is set by app.media. addStockEvents or by methods that call addStockEvents indirectly, such as app.media. openPlayer.

data-id=71321

data-id=defaultsize

data-id=id23

defaultSize

A read-only object containing the width and height of the MediaPlayer’s MediaClip:

{ width: number, height: number }

If the media player is unable to provide this value, it is undefined.

data-id=51225

data-id=doc

data-id=id24

doc

A reference to the Doc that owns the MediaPlayer.

data-id=12391

data-id=events

data-id=id25

events

An Events object containing the EventListeners that are attached to a MediaPlayer. See Events object for details.

Example: Create a media player, then modify the events of that player. The script is executed as a Rendition action with an associated rendition.

var events = new app.media.Events;
var player = app.media.createPlayer();
player.events.add({
    onReady: function() { console.println("The player is ready"); }
});
player.open();

data-id=77116

data-id=hasfocus

data-id=id26

hasFocus

A Boolean value that is true if the media player is open and has the keyboard focus.

data-id=94578

data-id=id

data-id=id27

id

The player ID for the player software that this player is using. It is undefined if the player has not been opened. This player ID is the same value that is found in PlayerInfo.id for the media player software that implements this player.

Example: Print the player ID to the console.

// Assume args has been defined
var player = app.media.openPlayer( args )
console.println("player.id = " + player.id);
// In the console, this script could possibly print...
player.id = vnd.adobe.swname:ADBE_MCI

data-id=49000

data-id=innerrect

data-id=id28

innerRect

A rectangle array representing the player’s inner rectangle. As with other such arrays in JavaScript, the coordinates are in the order [left, top, right, bottom]. The rectangle does not include a window title or other such gadgets around the edges of the player, but it does include the player controller, if present. It is undefined if the player is not open.

For a docked media player, this rectangle is in device space and is read-only (it throws an exception if you try to set it). Instead, use triggerGetRect to cause a docked player to be resized. For a floating media player, the rectangle is in screen coordinates and is writable, but the user’s security settings may override a value you set here. For example, if you try to move a floating media player offscreen, it may be forced back on-screen. This will not throw an exception. You can read this property after writing it to see if your value was overridden.

See also outerRect.

data-id=49436

data-id=isopen

data-id=id29

isOpen

A Boolean value that is true if the media player is currently open. Use MediaPlayer.open and MediaPlayer.close to open or close a player.

data-id=91927

data-id=isplaying

data-id=id30

isPlaying

A Boolean value that is true if the media is currently playing. It is false if the player is not open, or if the media is paused, stopped, fast forwarding or rewinding, or in any other state.

data-id=54328

data-id=id31

markers

A collection of all the markers available for the current media.

See Markers object for details of this property.

Example: See seek for an illustration of usage.

data-id=58125

data-id=outerrect

data-id=id32

outerRect

A rectangle array representing the player’s outer rectangle. As with other such arrays in JavaScript for Acrobat, the coordinates are in the order [ left, top, right, bottom ]. This rectangle includes any player controller, window title, and other such gadgets around the edges of the player. It is undefined if the player is not open.

For a docked media player, this rectangle is in device space and is read-only. It will throw an exception if you try to set it. Instead, use MediaPlayer.triggerGetRect to cause a docked player to be resized. For a floating media player, the rectangle is in screen coordinates and is writable, but the user’s security settings may override a value you set here. For example, if you try to move a floating media player offscreen, it may be forced back on-screen. This will not throw an exception. You can read this property after writing it to see if your value was overridden.

See also innerRect.

data-id=48828

data-id=page

data-id=id33

page

The page number in which a docked media player appears. It is undefined for players that are not docked. A docked media player can be moved to another page by changing its page property, which triggers a GetRect (see onGetRect) event.

Example: Play a media clip on page 1 (base zero). The placement of the media player on page 1 is the same as the screen annotation on page 0.

var player = app.media.openPlayer({
        rendition: this.media.getRendition( "myClip" ),
        annot: this.media.getAnnot({ nPage:0, cAnnotTitle:"myScreen" }),
        settings: { windowType: app.media.windowType.docked }
    });
player.page = 1;

See onGetRect and triggerGetRect for variations on this example.

data-id=31898

data-id=settings

data-id=id34

settings

Includes all of the settings that are used to create a MediaPlayer. See MediaSettings object for a complete list.

Note

In Acrobat 6.0, changing a property in MediaPlayer.settings after the player has been created has no effect. This may be changed in a future release to make these settings live. For compatibility with current and future releases, avoid changing any settings properties while a player is open.

data-id=51769

data-id=uisize

data-id=id35

uiSize

An array containing the size of the controller of the player for each edge of the player, in the same order as a window rectangle: [ left, top, right, bottom ]. Each of these values is normally a positive value or zero. These values do not include window gadgets such as title bars.

This property is not available until the Ready event is triggered (see onReady and afterReady). Unlike most MediaPlayer properties, it is permissible to read it during an on event method such as onReady.

Example: Get the uiSize of the player. This code is executed as a Rendition action event.

var args = {
    events: {
        onReady: function () {
            console.println("uiSize = " + player.uiSize );
        }
    }
};
var player = app.media.openPlayer(args);

data-id=96180

data-id=visible

data-id=id36

visible

A Boolean value controlling whether the player is visible. Unlike MediaPlayer.settings.visible, this property takes effect immediately. If the player is not open, reading this property returns undefined and setting it throws an exception.

Setting this property may trigger events. For example, if the player is visible and has the focus, making it invisible triggers a Blur event.

Example: Play the audio only of a video clip

// Assume a definition of args
var player = app.media.openPlayer(args);
player.visible = false;

data-id=mediaplayer-methods

data-id=id37

MediaPlayer methods

data-id=11397

data-id=close

data-id=id38

close

Closes the media player if it is open. Does nothing (and is not an error) if the player is closed.

The eReason parameter should be a value from the app.media.closeReason enumeration. This value is passed through to the event.media.closeReason property for the Close event (see onClose and afterClose) that the close method is triggered.

If the player has the keyboard focus, a Blur event (onBlur or afterBlur) is triggered before the Close event. Other events, such as Status (onStatus or afterStatus) and Stop (onStop or afterStop), may also be triggered depending on the particular media player.

Parameters

data-id=50913

data-id=open

data-id=id39

open

Attempts to open the media player as specified by MediaPlayer.settings. If the player is already open, an exception is thrown. If the player was previously opened and then closed, open may be called to open the player again. This uses the same JavaScript object as before but opens a new instance of the actual media player. In this case, for example, the new player does not remember the playback position from the old player.

For a docked player, a GetRect event (onGetRect) is triggered when the player is opened.

If MediaPlayer.settings.autoPlay is true (the default), playback begins and a Play event (onPlay or afterPlay) is triggered.

The open method may result in a security prompt dialog box, depending on the user’s settings. It may also result in events being triggered in objects such as other media players and screen annotations. For example, if another media player has the keyboard focus, it will receive a Blur event (onBlur or afterBlur).

If bAllowSecurityUI is false, the open method never displays a security prompt, but returns a failure code instead.

For a media player in a floating window, additional security checks are made against the user’s settings. For example, the user may specify that title bars are required on all floating player windows. If MediaPlayer.settings.floating contains options that the user does not allow, bAllowFloatOptionsFallback controls what happens. If it is false, playback is disallowed and an error code is returned. If it is true, the options in MediaPlayer.settings.floating are changed as needed to conform to the user’s security settings and open proceeds with those changed settings.

The return value is an object that currently contains one property, code, which is a result code from the app.media.openCode enumeration. If your PDF is opened in a future version of Acrobat, there may be additional properties in this object, or a code value added in that future version. Be sure to handle any such values gracefully.

Parameters

Returns

An object with a code property

Example: See createPlayer for an example of usage.

data-id=37680

data-id=pause

data-id=id40

pause

Pauses playback of the current media and triggers a Pause event (onPause or afterPause). The Pause event may occur during the pause call or afterward, depending on the player.

The pause method has no effect if the media is already paused or stopped, or if playback has not yet started or has completed. Not every media player and media format supports pause. In particular, most streaming formats do not support pause. Players may either throw an exception or silently ignore pause in these cases.

Example: See seek for an example of usage.

data-id=61004

data-id=play

data-id=id41

play

Starts playback of the current media and triggers a Play event (onPlay or afterPlay). The Play event may occur during the play call or afterward, depending on the player.

If the media is already playing, it continues playing and no event is triggered. If it is paused, rewinding, or fast forwarding, it resumes playback at the current position. If it is stopped, either at the beginning or end of media, playback starts from the beginning.

Example: See Example 2 after `seek.

data-id=41580

data-id=seek

data-id=id42

seek

Sets the current media’s playback location to the position described by the MediaOffset object contained in oMediaOffset.

If the media is playing, it continues playing at the new location. If the media is paused, it moves to the new location and remains paused there. If the media is stopped, the result will vary depending on the player.

Media players handle seek errors in different ways. Some ignore the error and others throw a JavaScript exception.

Most, but not all, media players trigger a Seek event (onSeek or afterSeek) when a seek is completed.

The seek operation may take place during the execution of the seek method or later, depending on the player. If seek returns before the seek operation is completed and you call another player method before the seek is completed, the results will vary depending on the player.

Parameters

Example 1:

// Rewind the media clip
player.seek({ time: 0 });

// Play starting from marker "First"
player.seek({ marker: "First" });

// Play starting five seconds after marker "One"
player.seek({ marker: "One", time: 5 });

data-id=93265

Example 2:

The following script randomly plays (famous) quotations. The media is an audio clip (.wma) of famous quotations, which supports markers and scripts. The afterReady listener counts the number of markers, one at the beginning of each quotation. At the end of each quotation, there is also an embedded command script. The afterScript listener watches for these commands and if it is a “pause” command, it pauses the player.

var nMarkers=0;
var events = new app.media.Events;
events.add({
    // Count the number of quotes in this audio clip, save as nMarkers
    afterReady: function()
    {
        var g = player.markers;
        while ( (index =  g.get( { index: nMarkers } ) ) != null )

             nMarkers++;
    },
    // Each quote should be followed by a script, if the command is to

     // pause, then pause the player.
    afterScript: function( e ) {
        if ( e.media.command == "pause" ) player.pause();
    }
});
var player = app.media.openPlayer({
    rendition: this.media.getRendition( "myQuotes" ),
    settings: { autoPlay: false },
    events: events
});
// Randomly choose a quotation
function randomQuote() {
    var randomMarker, randomMarkerName;
    console.println("nMarkers = " + nMarkers);
    // Randomly choose an integer between 1 and nMarkers, inclusive
    randomMarker = Math.floor(Math.random() * 100) % ( nMarkers ) + 1;
    // Indicate what quotation we are playing
    this.getField("Quote").value = "Playing quote " + randomMarker;
    // The marker names are "quote 1", "quote 2", "quote 3", etc.
    randomMarkerName = "quote " + randomMarker;
    // See the marker with the name randomMarkerName
    player.seek( { marker: randomMarkerName } );
    player.play();
}

Action is initiated by the mouse-up button action such as

try { randomQuote() } catch(e) {}

data-id=58878

data-id=setfocus

data-id=id43

setFocus

Sets the keyboard focus to the media player and triggers a Focus event (onFocus or afterFocus). If another player or PDF object has the focus, that object receives a Blur event (onBlur or afterBlur). If the media player already has the focus, nothing happens. If the player is not open or not visible, an exception is thrown.

Example: See createPlayer for an example of usage.

data-id=21014

data-id=stop

data-id=id44

stop

Stops playback of the current media, if it is playing or paused, and triggers a Stop event (onStop or afterStop). The Stop event may occur during execution of the stop method or afterward, depending on the player. Does nothing if the media is not playing or paused.

Throws an exception if the player is not open.

After playback stops, the player sets the media position to either the beginning or end of media, depending on the player. If MediaPlayer.play is called after this, playback starts at the beginning of media.

data-id=63484

data-id=triggergetrect

data-id=id45

triggerGetRect

Triggers a GetRect event (see onGetRect) to cause a docked media player to be resized.

Example: This example is similar to the one that follows onGetRect. Page 0 has a series of (thumbnail-size) ScreenAnnots. Below is a typical Rendition action or mouse-up button JavaScript action, when the action is executed, the media clip is resized and played.

var rendition = this.media.getRendition("Clip1");
var annot = this.media.getAnnot({ nPage:0,cAnnotTitle:"ScreenClip1" });
var player = app.media.openPlayer({
    rendition: rendition,
    annot: annot,
    settings: { windowType: app.media.windowType.docked },
    events: {
        onGetRect: function (e) {
            var width = e.media.rect[2] - e.media.rect[0];
            var height = e.media.rect[3] - e.media.rect[1];
            width *= 3; // Triple width and height
            height *= 3;
            e.media.rect[0] = 36; // Move left,upper to
            e.media.rect[1] = 36; // upper left-hand corner
            e.media.rect[2] = e.media.rect[0]+width;
            e.media.rect[3] = e.media.rect[1]+height;
            return e.media.rect; // Return this
        }
    }
});
player.triggerGetRect(); // trigger the onGetRec event

data-id=90314

data-id=where

data-id=id46

where

Reports the current media’s playback location in a MediaOffset object. This object contains either a time or frame property, depending on the media player and media type.

Throws an exception if the player is not open or if the player does not support where.

Returns

MediaOffset object

data-id=26770

Example: Obtain the playback location in seconds.

// This code assumes that the player supports where() using time.
var where = player.where();
var seconds = where.time;

Obtain the chapter (marker).

var marker = player.markers.get({ time: seconds });
var name = marker ? marker.name : "no marker";

data-id=16239

data-id=mediareject

data-id=id47

MediaReject

A MediaReject provides information about a Rendition that was rejected by a Rendition.select call. It includes a reference to the original Rendition along with the reason why it was rejected. In a MediaSelection object returned by select, MediaSelection.rejects is an array of MediaReject objects.

data-id=mediareject-properties

data-id=id48

MediaReject properties

data-id=31167

data-id=rendition

data-id=id49

rendition

A reference to the Rendition that was rejected in a select call.

data-id=55114

Get a list of rejected renditions. The script is executed as a Rendition action.

selection = event.action.rendition.select(true);
for ( var i=0; i<selection.rejects.length; i++)
    console.println("Rejected Renditions: "

         + selection.rejects[i].rendition.uiName);

// Now play the first available rendition.
console.println( "Preparing to play " + selection.rendition.uiName);
var settings = selection.rendition.getPlaySettings();
var args = {
    rendition: selection.rendition,
    annot: this.media.getAnnot({ nPage: 0, cAnnotTitle: "myScreen" }),
    settings: settings
};
app.media.openPlayer(args);

data-id=47359

data-id=mediaselection

data-id=id50

MediaSelection

The Rendition.select method returns a MediaSelection object that can be used to create a MediaSettings object for playback.

data-id=mediaselection-properties

data-id=id51

MediaSelection properties

data-id=36039

data-id=selectcontext

data-id=id52

selectContext

A value that can be used to write a loop that calls Rendition.select repeatedly to do a customized selection based on any criteria that you can test in JavaScript code.

Example: Generic script for using selectContext.

function MyTestSelection( selection )
{
    // This function should test the selection as you wish and return
    // true to use it or false to reject it and try another one.
}
function MyGetSelection( rendition )
{
    var selection;
    for( selection = rendition.select(); selection;
        selection = rendition.select
            ({ oContext: selection.selectContext }))
    {
        if( MyTestSelection( selection ) )
            break;
    }
    return selection;
}

data-id=77091

data-id=players

data-id=id53

players

An array of strings identifying the media players that may be used to play MediaSelection.rendition. Both the players and rendition properties are null if no playable rendition is found.

data-id=81816

Example: Get a list of the players that will play the selected rendition. The code below assumes execution as a Rendition action.

var selection = event.action.rendition.select();
for ( var o in selection.players )
    console.println( selection.players[o].id );

data-id=83651

data-id=rejects

data-id=id54

rejects

An array of MediaReject objects. These are the Renditions that were rejected by the Rendition.select call that returned this MediaSelection. See MediaReject object for details.

Example: See rendition

data-id=11395

data-id=id55

data-id=id56

rendition

The selected rendition, or null if none was playable.

Example: Get the name of the selected rendition. This script is executed from a Rendition action event.

var selection = event.action.rendition.select();
console.println( "Preparing to play " + selection.rendition.uiName);

data-id=91559

data-id=mediasettings

data-id=id57

MediaSettings

A MediaSettings object contains settings required to create and open a MediaPlayer. It is the value of the settings property of the MediaPlayer object. Many of these settings have default values, but some are required depending on the type of player being opened and depending on other settings. See the notes for each MediaSettings property for details.

Acrobat and the various media players will attempt to use these settings, but there is no guarantee that they will all be honored. (For example, very few players honor the palindrome setting.)

data-id=mediasettings-properties

data-id=id58

MediaSettings properties

data-id=11885

data-id=autoplay

data-id=id59

autoPlay

Specifies whether the media clip should begin playing automatically after the player is opened. If you set autoPlay to false, use MediaPlayer.play to begin playback. The default value is true.

Example: See the examples following afterReady and players.

data-id=97037

data-id=baseurl

data-id=id60

baseURL

The base URL to be used to resolve any relative URLs used in the media clip, for example, if the media opens a web page. There is no default value; if baseURL is not specified, the interpretation of a relative URL will vary depending the media player, but in most cases will not work.

data-id=83870

data-id=bgcolor

data-id=id61

bgColor

The background color for the media player window. The array may be in any of the color array formats supported by JavaScript for Acrobat.

If bgColor is not specified, the default value depends on the window type:

• Docked: White
• Floating: The window background color specified in the operating system control panel
• Full Screen: The full screen background color specified in the user’s Acrobat preferences

data-id=13149

Example:

// Red background
settings.bgColor = [ "RGB", 1, 0, 0 ];

data-id=81817

data-id=bgopacity

data-id=id62

bgOpacity

The background opacity for the media player window. The value may range from 0.0 (fully transparent) to 1.0 (fully opaque). The default value is 1.0.

data-id=52881

data-id=data

data-id=id63

data

An object, often referred to as a MediaData object, that a media player can use to read its media clip data, whether from an external file or embedded in the PDF. The contents of this object are not directly usable from JavaScript.

This object can be obtained from app.media.getAltTextData, app.media.getURLData, or indirectly by Rendition.getPlaySettings. The data object may be bound to the rendition’s document, so it may become unavailable if the document is closed.

Example: See the examples that follow app.media. getURLData.

data-id=42027

data-id=duration

data-id=id64

duration

The amount of time in seconds that playback will take. If not specified, the default is to play the entire media, or the amount of time between the startAt and endAt points if either of those is specified.

Note that the duration may be longer than the entire media length or the difference between the startAt and endAt points. In that case, playback continues to the end of media or to the endAt point and then playback pauses at that location until the duration elapses.

Example: Play a floating window with infinite duration. The playback location (from the UI) of the rendition is a floating window. The code below is executed from a form button. The floating window remains open after the player has reached the end of the media. To avoid stacked floating windows, the player is closed before reopening it.

If this script is executed from a Rendition action, the rendition can be specified through the UI and closing the player would not be necessary.

var rendition = this.media.getRendition("Clip");
if ( player && player.isOpen )
    try { player.close(app.media.closeReason.done); } catch(e) {};
var player = app.media.openPlayer({
    rendition: rendition,
    settings: { duration: Infinity }
});

data-id=30733

data-id=endat

data-id=id65

endAt

The ending time or frame for playback. This may be an absolute time or frame value, or a marker name, or a marker plus a time or frame, as described under MediaOffset object. Playback ends at the specified time or frame, or as close to that point as the media player is able to stop. If endAt is not specified, the default value is the end of media.

See also startAt.

Example: The following script plays an audio clip beginning 3 seconds into the media to 8 seconds into the media.

var player = app.media.openPlayer({
    rendition: this.media.getRendition( "myAudio" ),
    doc: this,
    settings: {
        startAt: 3,
        endAt: 8
    }
});

data-id=16893

data-id=floating

data-id=id66

floating

An object containing properties (listed below) that define the location and style of a floating window.

This object is ignored unless MediaSettings.windowType has a value of app.media.windowType.floating.

Defaults are used for all the floating settings if they are not specified.

Example: Play a media clip in a floating window.

var rendition = this.media.getRendition( "myClip" );
var floating = {
    align: app.media.align.topCenter,
    over: app.media.over.appWindow,
    canResize: app.media.canResize.no,
    hasClose: true,
    hasTitle: true,
    title: rendition.altText,
    ifOffScreen: app.media.ifOffScreen.forceOnScreen,
    width: 400,
    height: 300
};
var player = app.media.openPlayer({
    rendition: rendition,
    settings: {
        windowType: app.media.windowType.floating,
        floating: floating
    }
});

data-id=17615

data-id=layout

data-id=id67

layout

A value chosen from the app.media.layout enumeration, which defines whether and how the content should be resized to fit the window. The default value varies with different media players.

data-id=19974

data-id=monitor

data-id=id68

monitor

For a full screen media player, this property determines which display monitor will be used for playback. This may be either a Monitor object or a Monitors object. If it is an array, the first element (which is a Monitor object) is used.

Note

Only the rect property MediaSettings.monitor. rect (in the case of a Monitor object) or MediaSettings.monitor[0]. rect (for a Monitors object) is used for playback.

See monitorType (below) for a discussion of the relationship between the monitor and monitorType properties.

Example: Play a media clip in full screen from a form button.

var player = app.media.openPlayer({
    rendition: this.media.getRendition("Clip"),
    settings: {
        monitor: app.monitors.primary(),
        windowType: app.media.windowType.fullScreen,
    }
});

Note

The user trust manager settings must allow full screen play back.

data-id=26076

data-id=monitortype

data-id=id69

monitorType

An app.media.monitorType value that represents the type of monitor to be selected for playback for a floating or full screen window.

Note the difference between the monitor and monitorType properties:

• monitor specifies a specific monitor on the current system by defining its rectangle.
• monitorType specifies a general category of monitor based on attributes such as primary, secondary, and best color depth.

A PDF file that does not use JavaScript cannot specify a particular monitor, but it can specify a monitor type. When monitorType is specified in a call to app.media.createPlayer or app.media.openPlayer, JavaScript code gets the list of monitors available on the system and uses monitorType to select one of the monitors for playback. The monitor rectangle is then used when MediaPlayer.open is called to select the monitor.

Example: Play a media clip in full screen on a monitor with the best color depth.

var player = app.media.openPlayer({
    rendition: this.media.getRendition("Clip"),
    settings: {
        monitorType: app.media.monitorType.bestColor,
        windowType: app.media.windowType.fullScreen,
    }
});

data-id=37286

data-id=id70

data-id=id71

page

For a docked media player, this property is the number of the page on which the player should be docked. For other types of media players, this property is ignored.

See also MediaPlayer. page.

data-id=30683

data-id=palindrome

data-id=id72

palindrome

If this property is true, the media plays once normally and then plays in reverse back to the beginning. If repeat is specified, this forward-and-reverse playback repeats that many times. Each complete forward and reverse playback counts as one repeat.

The default value is false.

Note

Most media players do not support palindrome and ignore this setting.

Example: Use QuickTime, which supports palindrome, to view the media clip.

var playerList = app.media.getPlayers().select({ id: /quicktime/i });
var settings = { players: playerList, palindrome: true };
var player = app.media.openPlayer({ settings: settings });

The above code should be run within a Rendition action event with an associated rendition.

data-id=22715

data-id=id73

data-id=id74

players

An array of objects that represent the media players that can be used to play this rendition. JavaScript code does not usually access this array directly but passes it through from Rendition.select to the settings object for app.media.createPlayer.

Example: List the available players that can play this rendition. This script is run as a Rendition action with associated rendition.

var player = app.media.openPlayer({ settings: {autoPlay: false} });
console.println("players: " + player.settings.players.toSource() );

// Sample output to the console:
players: [{id:"vnd.adobe.swname:ADBE_MCI", rank:0},

 {id:"vnd.adobe.swname:AAPL_QuickTime", rank:0},

 {id:"vnd.adobe.swname:RNWK_RealPlayer", rank:0},

 {id:"vnd.adobe.swname:MSFT_WindowsMediaPlayer", rank:0}]

data-id=86332

data-id=rate

data-id=id75

rate

A number that specifies the playback rate. The default value is 1, which means normal playback. Other values are relative to normal speed. For example,.5 is half speed, 2 is double speed, and -1 is normal speed in reverse.

Many players and media types are limited in the values they support for rate and will choose the closest playback rate that they support.

Example: Play a media clip at double speed. This script is executed as a Rendition action.

var player = app.media.createPlayer();
player.settings.rate = 2;
player.open();

data-id=94336

data-id=repeat

data-id=id76

repeat

The number of times the media playback should automatically repeat. The default value of 1 causes the media to be played once.

Many players support only integer values for repeat, but some allow non-integer values such as 1.5. A value of Infinity plays the media clip continuously.

The default value is 1.

Example: Play a media clip from a Rendition action continuously.

var player = app.media.openPlayer({settings: { repeat: Infinity } });

data-id=22987

data-id=showui

data-id=id77

showUI

A Boolean value that specifies whether the controls of the media player should be visible or not.

The default value is false.

Example: Show the controls of the media player. This script is executed as a Rendition action.

var player = app.media.createPlayer();
player.settings.showUI = true;
player.open();

or

app.media.openPlayer( {settings: {showUI: true} });

data-id=25011

data-id=startat

data-id=id78

startAt

Defines the starting time or frame for playback. This may be an absolute time or frame value, or a marker name, or a marker plus a time or frame, as described under MediaOffset. Playback starts at the specified time or frame, or as close to that point as the media player is able to stop. If startAt is not specified, the default value is the beginning of media.

See also endAt.

Example: See the example that follows endAt.

data-id=44957

data-id=id79

data-id=id80

visible

A Boolean value that specifies whether the player should be visible.

The default value is true.

Example: Set a docked media clip to play audio only. The script is executed as a Rendition action.

   var args = {
       settings: {
           visible: false,
           windowType: app.media.windowType.docked
       }
   };
app.media.openPlayer( args );

See also MediaPlayer. visible.

data-id=97636

data-id=volume

data-id=id81

volume

Specifies the playback volume. A value of 0 is muted, a value of 100 is normal (full) volume; values in between are intermediate volumes. Future media players may allow values greater than 100 to indicate louder than normal volume, but none currently do.

The default value is 100.

data-id=46521

data-id=windowtype

data-id=id82

windowType

A value, chosen from the app.media.windowType enumeration, that defines what type of window the MediaPlayer should be created in.

If you use the low-level function doc.media.newPlayer, the default value for windowType is app.media.windowType.docked.

If you use the higher-level createPlayer or openPlayer functions of the app.media object, the default value is determined as follows:

• If an annot is provided (see the description of the PlayerArgs object), the default is app.media.windowType.docked.
• If a settings.floating object is provided (see the description of the PlayerArgs object), the default is app.media.windowType.floating.
• Otherwise, the default is undefined.

Example: Create media players with different window types. Script is executed as a Rendition action, so the selection of the specification of the rendition is not needed.

// Docked player that will be played in the associated ScreenAnnot
app.media.openPlayer({
    settings: { windowType: app.media.windowType.docked }
});
// Play in full screen mode, see also monitor and monitorType
app.media.openPlayer({
    settings: { windowType: app.media.windowType.fullScreen }
});
// Show the media clip in a floating window, also, see the floating property
var args = {
    settings: {
        windowType: app.media.windowType.floating,
        floating: {
            title: "A. C. Robat",
            width: 352,
            height: 240,
        }
    }
};
app.media.openPlayer( args );

data-id=80470