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.
Comments