PAL Object - TPlayer

TPlayer

Use this object to control a player. DeckA, DeckB, Aux1, Aux2, Aux3 and SoundFX are all player types (Class TPlayer) This means that all of the same operations apply to all of these players.

PAL comes with some very handy built-in functions you can use. These provide you with direct access to the correct player object. (Between DeckA & DeckB only!)

ActivePlayer

This returns the player object considered the "active" player. If only one deck is player a track, then this track will be the active player. If both decks are playing a track, then the deck with the longest duration remaining is considered the active deck. If NEITHER DeckA or DeckB have any tracks playing, then this function returns NIL. It is very important that you check for the NIL value, unless you are certain that there will always be an active deck.

IdlePlayer

A Deck is considered Idle if no song is queued up in the deck, and the deck is not actively playing any tracks. If both decks are idle, DeckA is returned as the idle object. If both decks are queued up, or actively playing a track - then this function will return NIL!

QueuedPlayer

A player is considered in Queued mode if the Deck has a song object loaded into the Deck, but the Deck is not currently actively playing any tracks. If both decks are either idle or active, then this function will return NIL! Otherwise it will return the first Queued deck.

Properties

CurTime

Declaration

property CurTime: Integer;

Description

Read-onlyCurrent playback position of track in milliseconds.

The CurTime property can be monitored to see when a song is approaching its end (when compared to the Duration property) and then action can be taken right before the next song is started or queued.

Example:

Var Done : Boolean = False;

While not done do begin if((ActivePlayer.Duration>0) AND ((ActivePlayer.Duration-ActivePlayer.CurTime)>10000)) then begin WriteLn('This song will end in 10 seconds!'); Done := True; end; end;

Note: Due to the gap killer, it may be less than 10 seconds. You can use the actual value of the calculation to get the correct value of the time remaining.

Duration

Declaration

property Duration: Integer;

Description

Read-onlyDuration of the track in milliseconds.

Status

Declaration

property Status: Integer;

Description

Read-onlyReturns the current status of the player, which can be any of the following constants.

0 - Player is currently playing a track1 - Player is empty and idle (no track loaded)2 - Player is paused but with a track loaded

Example:

Volume

Declaration

property Volume: Integer;

Description

Read/WriteRead or Set the volume of the player. Volume ranges from 0 (Silent) to 255 (Loud).

You can read and write the Volume property of a Deck. This can be used to play advertisements, stationIDs, etc. louder than other tracks. We recommend you use the song information editor to set the Gain for each track of these audio content types, but this script might be an alternative solution.

QueueSong

Declaration

Description

Ejects any currently playing/paused track in the player and loads the new track into the player.

If you manually create the Song object, make sure you set at least the Filename, ID and Duration fields of the song information object.

In this example we play a station ID exactly on-the-hour. In fact, we fade out any currently playing song to make sure it plays. We also load the station ID directly into the player.

Example:

var P : TPlayer;var Song : TSongInfo;

PAL.Loop := True;

{## Wait for "on-the-hour"}PAL.WaitForTime('XX:00:00');

{## Detect the empty player and queue a station ID in it}P := IdlePlayer;if P <> nil then begin Song := CAT['Station IDs (All)'].ChooseSong(smRandom,NoRules); if Song <> nil then P.QueueSong(Song); {## Detect the active player and start the fade-out} P := ActivePlayer; if P <> nil then P.FadeToNext; end;

Seek

Declaration

function Seek(Time: Integer): Integer;

Description

Seeks to the specified Time in playback.

Time is specified in milliseconds.

The actual time position after the seek is returned.

The following would cause the song to jump to 1 minute if there is a song on Deck A where it would start playback from the 1 minute point.As the time is specified in milliseconds we need to know that there are 60,000 milliseconds in a minute, (60000/1000 = 60 seconds or 1 minute)

Example:

DeckA.Seek(60000 );

Eject

Declaration

procedure Eject;

Description

Immediately unloads any track loaded into the player, even if it is currently playing.

Eject the current song that is in the Active Deck

Example:

ActivePlayer.Eject;

FadeToNext

Declaration

procedure FadeToNext;

Description

Start fading out the current player and eject the current track once the fade-out is complete. The next track will start playing.

In this example we play a station ID exactly on-the-hour. In fact, we fade out any currently playing song to make sure it plays. We also load the station ID directly into the player.

Example:

var P : TPlayer;var Song : TSongInfo;

PAL.Loop := True;

{## Wait for "on-the-hour"}PAL.WaitForTime('XX:00:00');

{## Detect the empty player and queue a station ID in it}P := IdlePlayer;if P <> nil thenbegin Song := CAT['Station IDs (All)'].ChooseSong(smRandom,NoRules); if Song <> nil then P.QueueSong(Song);

{## Detect the active player and start the fade-out}

P := ActivePlayer; if P <> nil then P.FadeToNext;

FadeToPlay

Declaration

procedure FadeToPlay;

Description

The player must be in the "ready" state for this to work properly, this is where a track is loaded into the player, but is currently paused.

FadeToPlay will start playing the song and fade the song in from silence to full volume.