Follow

PAL Object - TPlayer

TPlayer

The TPlayer object is used to play songs inside SAM Broadcaster.

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-only
Current 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-only
Duration of the track in milliseconds.


Status

Declaration

property Status: Integer;

Description

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

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

Example:

// find out if DeckA is playing, ready or queued
Var Done : Boolean = False;
Var PlayerStatus : integer;

PlayerStatus := DeckA.Status;
writeln(IntToStr(PlayerStatus)); // writes the status of DeckA

Volume

Declaration

property Volume: Integer;

Description

Read/Write
Read 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.

Example:

var Done : Boolean = False;
var Song : TSongInfo;

While not Done do
begin
if QueuedPlayer <> nil then
begin
Done := True;
Song := QueuedPlayer.GetSongInfo;
if (Song<>nil) then
case song['songtype'] of
'S' : QueuedPlayer.Volume := 255;
      'A','J','P' : QueuedPlayer.Volume := 350;
      else QueuedPlayer.Volume := 255;
end; //case
end;
end;

PAL.Loop := True;
PAL.WaitForPlayCount(1);


Note: 255 is full volume, while 350 is volume with extra gain applied.


CanSeek

Declaration

property CanSeek: Boolean;

Description

Read-only
Returns true if the player is able to seek to a specific time in the current track.

 

For example, for most internet stream sources the player is unable to seek inside the stream to a specific point in time.


Paused

Declaration

property Paused: Boolean;

Description

Read/Write
Read or Set the current player's paused status.


The following example checks to see if DeckA is paused if not then DeckA is paused.

Example:

writeln(DeckA.Paused);
if (DeckA.Paused = False)   then
DeckA.Paused := True;
writeln(DeckA.Paused);

Pitch

Declaration

property Pitch: Integer;

Description

Read/Write
Read or Set the pitch of the player. Valid pitch values range from -50 (Slow) to +50 (Fast).

 

A value of zero means normal pitch.
This property basically adjusts the frequency to speed up or slow down the audio.

A simple example that writes the Pitch to the Output window and then sets the pitch to 25 for DeckA

Example:

writeln(DeckA.Pitch);
DeckA.Pitch :=   25;
writeln(DeckA.Pitch);

Tempo

Declaration

property Tempo: Integer;

Description

Read/Write
The Tempo changes the speed of the audio, without effecting the pitch or frequency.

Read or Set the Tempo of the player. Valid Tempo values range from -50 (Slow) to 50 (Fast)
A value of zero means normal tempo.

Example writes the current Tempo value out then sets it to 25

Example:

writeln(DeckA.Tempo);
DeckA.Tempo :=   25;
writeln(DeckA.Tempo);

Methods

GetSongInfo

Declaration

function GetSongInfo: TSongInfo;

Description

Returns the song information object of the currently playing track in the player.
Returns nil if the player does not have a track loaded.

This script will read the song information of the track loaded into DeckA, and then print out the information.

Example:

var Song : TSongInfo;

Song := DeckA.GetSongInfo;

if Song = nil then
WriteLn('No song loaded into DeckA!')
else
begin
WriteLn('Artist: '+Song['artist']);
WriteLn('Title: '+Song['title']);
WriteLn('Album: '+Song['album']);
WriteLn('Duration: '+Song['duration']);
end;

Song.Free;

QueueSong

Declaration

function QueueSong(Song: TSongInfo): Boolean;

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 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;

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.

Pause the active Deck wait 10 seconds then start the deck.

Example:

ActivePlayer.FadeToPause;
PAL.WaitForTime('+00:00:10'); //wait 10 Seconds
ActivePlayer.FadeToPlay;

FadeToPause

Declaration

procedure FadeToPause;

Description

Start fading out the current player and pause the current track once the fade-out is complete.

Example:

ActivePlayer.FadeToPause;
PAL.WaitForTime('+00:00:10'); //wait 10 Seconds
ActivePlayer.FadeToPlay;

Next

Declaration

procedure Next;

Description

Load the next track into the player. If the player is currently playing it will also start playing the new track.


The example code would cause DECK A to load the next song in the queue and play it.

Example:

DeckA.Next;

Pause

Declaration

procedure Pause;

Description

If the player is currently playing a track, the track will be paused whilst a paused track will start playing again.

Example:

var ispaused : boolean ;

ispaused := DeckA.Paused;

if ispaused then
writeln(DeckA.Paused )
else
DeckA.Pause; //pause it if its not

Play

Declaration

procedure Play;

Description

Start playing any paused or loaded track.


A simple example of starting DeckA if it is paused.

Example:

var ispaused : boolean ;

ispaused := DeckA.Paused;

if ispaused then
DeckA.Play   //start the deck playing
else
DeckA.Pause; //pause it if its not

Stop

Declaration

procedure Stop;

Description

Stop any track playing in the player.


Stop the Active Deck

Example:

ActivePlayer.Stop

AGCLoadPreset

Declaration

procedure AGCLoadPreset(Filename : String);

Description

Loads a preset for the AGC of the player from file.


AGCSavePreset

Declaration

procedure AGCSavePreset(Filename : String);

Description

Save the current AGC preset to file.


 

Was this article helpful?
0 out of 1 found this helpful
Have more questions? Submit a request

Comments