Name: play

Type: command

Syntax: play [<clipType>] {<filePath> | <clip>} [looping] [at <point>] [options <xOptions>]

Syntax: play {stop | pause | resume | step {forward | back}} [<clipType>] [<clip>]

Summary:
Plays a movie or sound.

Introduced: 1.0

OS: mac, windows, linux, ios

Platforms: desktop, server, mobile

Example:
play "/usr/local/clips/music.aiff"

Example:
play videoClip "Movie" at 100,100

Example:
play audioClip "Trust No One" looping

Example:
play "/usr/local/clips/music.aiff"

Example:
# to stop the currently playing audio clip
play stop

Parameters:
clipType (enum):
The type of clip to play.

- audioClip
- videoClip

filePath:
The location and name of the file you want to play. If you specify a
name but not a location, LiveCode assumes the file is in the
defaultFolder. 

clip:
A reference to an audio clip or video clip in an open stack.

point:
Specifies the center of the movie to be played, relative to the current
stack window. If the <point> is not specified, the movie is positioned
at the center of the current card. If a sound is being played, the
<point> has no effect.

xOptions:
Are command line parameters passed to the "xanim" package on Unix
systems. (On Mac OS and Windows systems, this parameter has no effect.).

The result:
To pause a movie, use the play pause form. Continue playing with play
resume. You can move one frame backward or forward with the play step
form. If you use one of these commands with a <clip> that is not
currently playing, the <result> <function> <return|returns>
"videoClip is not playing". If the <clip> is a sound, these forms simply
play the sound, ignoring the words "pause", "resume", or "step" .The
<play> <command> does not work on some <Unix|Unix systems> that lack
built-in support for sound. On these systems, when the <play> <command>
<execute|executes>, the <result> is set to "no sound support".

Description:
Use the <play> <command> to control playing of a movie or sound. 

If you use the play ... looping form, the sound or video plays
continuously from beginning to end until you stop it.

You can stop playing of a movie or sound with the <stop> <command> or
with the play stop form. If you specify a <clip>, only that clip is
stopped. If you specify a <type> but not a <clip>, the last clip of that
type is stopped. (On <Unix|Unix systems>, you must wait a second or two
after starting a movie or sound before you can stop it, to give the
external player time to start up.)

You can play multiple movies at once by starting each one of them with
the <play> <command>.

Movies cannot be played while any tool other than the Browse tool is in
use. 

If you start playing an audio clip when another one is playing, the
first audio clip is stopped, and a <playStopped> <message> is sent to
the <current card>. You cannot play two sounds at the same time, nor can
you queue a sound while another sound is playing.

On Unix systems, the "xanim" program must be located in a directory in
the PATH <environment variable>. You can set the PATH from within LiveCode
by using the put <command> :

    put newPath into $PATH

> *Note:* The type of audio and video clip formats supported  
> by the <play> command is limited. See the entries for <audioClip> 
> and <videoClip> for details. To play a wider variety of formats, 
> use a <player> object.

Changes:
The use of <QuickTime> was deprecated in version 8.1 of LiveCode. As
the `play videoClip ..` form of the <play> command was relying on 
<QuickTime>, it is no longer supported.

References: audioClip (object), beep (command), callbacks (property), 
command (glossary), current card (glossary), currentTime (property), 
dontRefresh (property), environment variable (glossary), 
execute (glossary), frameCount (property), function (control structure), 
import (command), iphoneSetAudioCategory (command), looping (property), 
MCISendString (function), message (glossary), 
playDestination (property), player (object), playLoudness (property), 
playRate (property), playStarted (message), playStopped (message), 
prepare (command), QTVersion (function),  QuickTime (glossary), 
result (function), return (glossary), revStopAnimation (command), 
showSelection (property), sound (function), start (command), 
stop (command), Unix (glossary), videoClip (object)

Tags: multimedia

