We are in the process of migrating the Spacial Wiki content to our new Help Center at spacial.com.
Please visit the Help Center for latest Tips and Tricks, Documentation and Troubleshooting.
spacial.com/help-center

TPlayer

From SpacialAudio

Jump to: navigation, search

Link To Other PAL Articles

Table of Contents   Quick Start Guide   PAL Scripting 101   Objects   Script Examples    Music1 24 Hour PAL Script    Music 1 Hourly PAL   CBS News Scripts    Write some useful scripts


Contents

General Info

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.

Overall the ActivePlayer function is used much more than any of the others. Most of our examples will deal with this function.

Top





Properties and Methods


Properties

CurTime   Duration   Status   Volume   CanSeek   Paused   Pitch   Tempo   


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 some action can be taken right before the next song is started or queued.
For 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.


Properties   Top


Duration

Declaration
property Duration: Integer;

Description
Read-only
Duration of the track in milliseconds.


Properties   Top


Status

Declaration
property Status: Integer;

Description
Read-only

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

psPlaying = 0; Player is currently playing a track
psReady = 1; The player is empty (No track loaded)
psQueued = 2; A track is loaded into the player, but is currently paused

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

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

Properties   Top


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 player 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.
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);

Once again, this is not the recommended method - but it does serve as a good example of how to use the volume option in PAL.
Note: 255 is full volume, while 350 is volume with extra gain applied.

Properties   Top


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.


Properties   Top


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 it pauses it

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

Properties   Top


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

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



Properties   Top


Tempo

Declaration
property Tempo: Integer;

Description
Read/Write

The Tempo changes the speed of the audio, without effecting the pitch or frequency.
This means the audio will not sound like the Smurths at higher speeds, nor will it sound like the deamons from hell at lower speeds!
This is perfect for beat-matching songs without distorting the music.
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

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


Properties   Top



Methods

GetSongInfo    QueueSong   Seek   Eject   FadeToNext   FadeToPlay   FadeToPause   Next   Pause    Play    Stop    AGCLoadPreset   AGCSavePreset  

Top


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.

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

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;

Methods   Top


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.

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;



Methods   Top


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 just to 1 minute if there is a song on Deck A.
It would then start playback form the 1 minute mark. (60000/1000 = 60 seconds or 1 minute)

DeckA.Seek(60000 );



Methods   Top


Eject


Declaration
procedure Eject;

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

Eject song that is in the Active Deck

ActivePlayer.Eject;

Methods   Top


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 should start playing as well.

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

Methods   Top


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

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

Methods   Top


FadeToPause

Declaration
procedure FadeToPause;

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

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

Methods   Top


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.

DeckA.Next;

Methods   Top


Pause

Declaration
procedure Pause;

Description
If the player is currently playing a track, the track will be paused.
A paused track on the other hand will start playing again.

This example checks to see if DeckA is paused. If its not then it is Paused.
Not sure how useful this is , but it is an example of usage.

var ispaused : boolean ;

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

Methods   Top


Play

Declaration
procedure Play;

Description
Start playing any paused or loaded track.

A simple example of starting DeckA if it is paused.

 var ispaused : boolean ;

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

Methods   Top


Stop

Declaration
procedure Stop;

Description
Stop any track playing in the player.

stop the Active Deck

ActivePlayer.Stop

Methods   Top


AGCLoadPreset

Declaration
procedure AGCLoadPreset(Filename : String);

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

Methods   Top


AGCSavePreset

Declaration
procedure AGCSavePreset(Filename : String);

Description
Save the current AGC preset to file.

Methods   Top



Link To Other PAL Articles

Personal tools