< Back to PlayItSoftware.com

PlayIt Live/Documentation/Plugins

From PlayIt Software Wiki
Jump to: navigation, search

Plugins allow you to customise PlayIt Live to your needs. Plugins work by installing code scripts that are executed by PlayIt Live, integrating with its features to enhance your experience.

Contents

Plugin scripts are written in the C# programming language, the same one used to create PlayIt Live. Plugin scripts can be added to PlayIt Live and can be set to Auto Start and launch when the application starts.

Plugins can be managed by going to Plugins > Plugin Manager. This window lists the plugins that have been added to PlayIt Live. To create a new plugin, go to File > New Plugin.... This will open a Plugin Editor window with a new plugin template. To open an existing plugin from file, go to File > Open Plugin... and select the plugin file. This will open a Plugin Editor window with the selected plugin script.

Plugin Editor

The Plugin Editor window mainly features the code editor. The plugin name can be entered at the top, this will be added to the Plugin Manager on PlayIt Live if the Add to PlayIt Live checkbox is selected. Select Auto Start to automatically execute the plugin when PlayIt Live is started. Use the Check Syntax button to ensure the code you have entered is valid. Click the Run Now button to execute and test your plugin. It is possible to log text throughout your plugin - the output from this can be seen by clicking the Show Log button.

Editing Code

Plugin scripts are written in C#. C# is a modern programming language developed by Microsoft and has been around since 2000. Due to its popularity and the vast array of documentation available for the language, it was perfect for developing plugins. Should you wish to learn about the C# language syntax, try Wikipedia.

The default template for a PlayIt Live plugin is:

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Windows.Forms;
    using PlayIt.PluginEngine;
 
    public class NewPlugin : Plugin<PlayItLiveApp>
    {
        public override void Run()
        {
            // called when application starts
            // Use App. to access application methods
        }
 
        public override void Cleanup()
        {
            // clean up here
        }
    }

This plugin template will be briefly explained below:

public class NewPlugin : Plugin<PlayItLiveApp>

This line indicates that this plugin is a class that derives from Plugin of type PlayItLiveApp. Essentially, this is a PlayIt Live plugin. If you like, you can change New Plugin to be a name of your choice.

public override void Run()
{
    // [code here]
}

These lines allow you in insert code that will be executed when the plugin is run. Use the App property to execute methods and properties in PlayIt Live.

public override void Cleanup()
{
    // [code here]
}

These lines allow you in insert code that will be execute when the plugin is about to stop.

To save the plugin, go to File > Save and select a location for the plugin. If you have selected Add to PlayIt Live on the plugin, then the plugin will appear in the list on the Plugin Manager.

Please see examples below of how to use the framework to create plugins.

Framework

This section details the class structure of the plugin framework for PlayIt Live. Each method and property is explained along with examples. Above some examples you may see using Some.Namespace - this should be added at the top of the plugin along with the other using statements.

PlayItLiveApp

public abstract class PlayItLiveApp
{
	public abstract void WaitUntilTime(string time);
	public abstract void WaitUntilTime(System.DateTime time);
	public abstract void WaitForPluginStop();
	public abstract void RegisterHotKey(Keys key, Action action);
	public abstract void RegisterHotKey(Keys key, Keys modifiers, Action action);
	public abstract void WaitForPluginStop();
	public abstract void Log(string message);
	public abstract LiveAssistMode LiveAssistMode { get; }
	public abstract CartBasedMode DecksMode { get; }
	public abstract Tracks Tracks { get; }
	public abstract Settings Settings { get; }
	public abstract TrackGroups TrackGroups { get; }
	public abstract PlayoutPattern PlayoutPattern { get; }
	public abstract QuickCarts QuickCarts { get; }
}

WaitUntilTime()

Wait until a specific time before continuing. Pass a string value that will be parsed to the near time in the future. It is possible to use wildcards (*) to match the next value in the future. Alternatively pass a DateTime object to specify a specific time.

Example
App.WaitUntilTime("23:50:00"); // wait until 23:50 (11:50pm)
App.WaitUntilTime("23:50"); // wait until 23:50 (11:50pm)
App.WaitUntilTime("**:45:00"); // wait until the next time that is 45 minutes past the hour
App.WaitUntilTime("**:45"); // wait until the next time that is 45 minutes past the hour
App.WaitUntilTime(new System.DateTime(2013, 01, 28, 19, 45, 00)); // wait until 28th Jan 2013 at 19:45 (7:45pm)

WaitForPluginStop()

Wait until the plugin is stopped. This is best placed at the end of the Run method, as the plugin will stop once the Run method has finished executing. If you wish to create background tasks in the Run method, you can keep the plugin alive by adding this method to the bottom of the Run method.

Example
App.WaitForPluginStop(); // keep alive

RegisterHotKey()

Available in PlayIt Live 1.04+

Registers a key (or modified key, such as CTRL+F1) to the main interface to trigger an action. Please note that using space or enter to trigger an action is not recommended - these keys can be used in other parts of the interface, such as search, so can cause unexpected results. Details on the Keys enumeration can be found here.

Examples
App.RegisterHotKey(Keys.F1, () =>  App.LiveAssistMode.StartPlayout()); // playout starts when F1 is pressed
App.RegisterHotKey(Keys.F2, () =>  App.LiveAssistMode.TogglePausePlayout()); // playout pauses/unpauses when F2 is pressed
App.RegisterHotKey(Keys.F3, () =>  App.LiveAssistMode.StopPlayout()); // playout stops when F3 is pressed
App.RegisterHotKey(Keys.F1, Keys.Control, () =>  App.LiveAssistMode.StartPlayout()); // playout starts when CTRL+F1 is pressed
App.WaitForPluginStop(); // This is required at the end to ensure the keys stay registered

Log()

Log a message to the Log window. To view the Log window, click Show Log on the Plugin Editor window.

Example
App.Log("Waiting until the top of the hour...");
App.WaitUntilTime("**:00");

LiveAssistMode

This class is used to control aspects of PlayIt Live when in Live-Assist mode.

public abstract class LiveAssistMode
{
	public abstract TrackQueueItem[] GetQueueItems();
	public abstract void ClearQueue();
	public abstract Track ChooseTrack();
	public abstract Track ChooseTrack(bool enforcePolicies);
	public abstract Track ChooseTrack(TrackGroup trackGroup, bool enforcePolicies);
	public abstract void ResetPlayoutPatternIndex();
	public abstract void QueueTrack(Track track);
	public abstract void QueueFile(string filePath);
	public abstract void QueueFile(string filePath, bool analyseForSilence);
	public abstract void StartPlayout();
	public abstract void TogglePausePlayout();
	public abstract void StopPlayout();
	public abstract void SetMode(PlayoutMode mode);
	public abstract void PlayNext();
	public event EventHandler<PlayerEventArgs> OnPlayerStart;
}

GetQueueItems()

Returns an array of TrackQueueItems representing any playing or future tracks in the queue. TrackQueueItems contain the time the track will play and the Track itself.

Example
TrackQueueItem[] queueItems = App.LiveAssistMode.GetQueueItems();

ClearQueue()

Available in PlayIt Live 1.04+

Clears any future non-playing items from the playout log.

Example
App.LiveAssistMode.ClearQueue();

ChooseTrack()

Choose a track from the database, based on the current playout policies. Use the enforcePolices parameter to ensure that no policy rules are violated when choosing the track. You can specify a track group to restrict the track that is chosen. ..

Examples
Track track = App.LiveAssistMode.ChooseTrack(); // choose a track, enforcing playout policies by default
Track track = App.LiveAssistMode.ChooseTrack(false); // choose a track, ignoring playout policies
using System.Linq;
...
 
// search for a track group called "Songs" and get the first result
TrackGroup songsGroup = App.TrackGroups.Search("Songs").FirstOrDefault(); 
 
// choose a track from this group, enforcing playout policies
Track track = App.LiveAssistMode.ChooseTrack(songsGroup, true);

ResetPlayoutPatternIndex()

Reset the current position of the playout pattern used when choosing tracks in Semi-Auto or Auto Mode. This can be used to reset the position at the top of the hour to ensure a popular track is played.

Example
App.WaitUntilTime("**:00"); // wait until top of the hour
App.LiveAssistMode.ResetPlayoutPatternIndex();

QueueTrack()

Queue a track to the end of the playout log.

Examples
using System.Linq;
...
Track track = App.Tracks.Search(t => t.Artist == "The Killers").First(); // find a track by The Killers
App.LiveAssistMode.QueueTrack(track);

StartPlayout()

Starts live-assist playout. This is the same as pressing the Play button on the master controls.

Example
App.LiveAssistMode.StartPlayout();

TogglePausePlayout()

Pauses live-assist playout. This is the same as pressing the Pause button on the master controls.

Example
App.LiveAssistMode.TogglePausePlayout();

StopPlayout()

Fades and stops live-assist playout. This is the same as pressing the Stop button on the master controls.

Example
App.LiveAssistMode.StopPlayout();

SetMode()

Sets the live-assist playout mode. This is the same as sliding the mode slider on the master controls. Pass a PlayoutMode enum as a parameter - possible here values are Auto, SemiAuto or Manual. Setting Auto mode will automatically start playout.

Example
App.LiveAssistMode.SetMode(PlayoutMode.Manual); // set manual mode
App.LiveAssistMode.SetMode(PlayoutMode.SemiAuto); // set semi-auto mode
App.LiveAssistMode.SetMode(PlayoutMode.Auto); // set auto mode

PlayNext()

Available in PlayIt Live 1.04+

Advances to the next player and fades out any playing players. If no players are playing, the first item in the log is started.

Example
App.LiveAssistMode.PlayNext();

OnPlayerStart event

The OnPlayerStart event is raised when any of the Live-Assist players start playing a track. The OnPlayerStart event is based on the EventHandler delegate type with the arguments sender (unused) and PlayerEventArgs which stores data about the player that raised the event and the track that was started. See the example below for usage.

Example
public override void Run()
{
	App.LiveAssistMode.OnPlayerStart += _OnPlayerStart; // subscribe to event
	App.WaitForPluginStop(); // wait until the plugin stops to continue subscribing
}
 
private void _OnPlayerStart(object sender, PlayerEventArgs args)
{
	// log the name of the track
	App.Log(string.Format("Now Playing: {0} - {1}", args.Track.Artist, args.Track.Title));
}

CartBasedMode

The CartBasedMode class is used to control Decks and QuickCarts. The parameter index mentioned below represents the zero-based index of the deck or cart. For example, 0 represents the first deck or cart. For QuickCarts, for example, with 5 QuickCarts per row, index 5 would represent the first QuickCart on the second row.

public abstract class CartBasedMode
{
	public abstract void Load(int index, Track track);
	public abstract void Load(int index, string filePath, bool analyseForSilence);
	public abstract void Play(int index);
	public abstract void TogglePause(int index);
	public abstract void Stop(int index);
	public abstract void Seek(int index, double seconds);
	public event EventHandler<PlayerEventArgs> OnPlayerStart;
}

Load()

Load a Track or audio file into the specified deck or cart.

Examples
Track track = App.Tracks.Search(t => t.Artist == "The Killers").First(); // find a track by The Killers
App.DecksMode.Load(1, track); // load into the 2nd deck
App.QuickCarts.DockedToBottom.Load(5, track) // load into the 6th QuickCart along the bottom
 
// load a track from file into the first QuickCart on the Wall (do not analyse for silence)
App.QuickCarts.Wall.Load(0, @"C:\Music\The Killers - Human.mp3", false);

Play()

Play a deck or cart by index.

Example
App.DecksMode.Play(0); // play the first deck

TogglePause()

Pause or resume a deck or cart by index.

Example
App.DecksMode.TogglePause(5); // pause or resume the 6th deck

Stop()

Fade and stop a deck or cart by index.

Example
App.QuickCarts.DockedToBottom.Stop(3); // fade and stop the 4th QuickCart

Seek()

Seek to a position on a deck or cart. Specify an index and a position in seconds.

Example
App.DecksMode.Seek(0, 30); // seek 30 seconds into the track on the first deck

OnPlayerStart event

The OnPlayerStart event is raised when any of the cart-based players (Decks or QuickCarts) start playing a track. The OnPlayerStart event is based on the EventHandler delegate type with the arguments sender (unused) and PlayerEventArgs which stores data about the player that raised the event and the track that was started. See the example below for usage.

Example
public override void Run()
{
	App.DecksMode.OnPlayerStart += _OnPlayerStart; // subscribe to event
	App.WaitForPluginStop(); // wait until the plugin stops to continue subscribing
}
 
private void _OnPlayerStart(object sender, PlayerEventArgs args)
{
	// log the name of the track
	App.Log(string.Format("Now Playing: {0} - {1}", args.Track.Artist, args.Track.Title));
}

Tracks

public abstract class Tracks
{
	public abstract void Add(Track track);
	public abstract void Edit(Track track);
	public abstract void Delete(Track track);
	public abstract IEnumerable<Track> Search(string search);
	public abstract IEnumerable<Track> Search(Predicate<Track> predicate);
	public abstract Track GetOne(string search);
	public abstract Track GetOne(Predicate<Track> predicate);
	public abstract IEnumerable<Track> GetAll();
}

Add()

Add a track to the system.

Example
var track = new Track();
track.Artist = "The Killers";
track.Title = "Human";
track.FilePath = @"C:\Music\The Killers - Human.mp3";
App.Tracks.Add(track);

Edit()

Edit a track already existing in the system.

Example
// change all tracks by "The Killers" to "Killers"
foreach(var track in App.Tracks.Search(t => t.Artist == "The Killers"))
{
	track.Artist = "Killers";
	App.Tracks.Edit(track);
}

Delete

Delete a track already existing in the system.

Example
// delete all tracks by The Killers
foreach(var track in App.Tracks.Search(t => t.Artist == "The Killers"))
{
	App.Tracks.Delete(track);
}

Search

Find a track by track name or using a Predicate. A text string search will match Artist - Title. A predicate defines a set of criteria that a Track must match to be returned by the search.

Examples
var tracks = App.Tracks.Search("The Killers");
var tracks = App.Tracks.Search(t => t.Artist == "The Killers"); // find tracks by artist "The Killers"
var tracks = App.Tracks.Search(t => t.Title == "Human"); // find tracks with title "Human"

GetOne

Find a single track by name or using a Predicate. This is the same as Search() above but only turns one object.

Examples
Track track = App.Tracks.GetOne("The Killers");

GetAll

Get all the tracks in the system. Useful for iterating over all the objects and dumping the tracks to file.

Example
// dump all the track details to a file called music.txt
foreach(Track track in App.Tracks.GetAll())
{
    System.IO.File.AppendAllText("music.txt", string.Format("{0}\t{1}\t{2}\r\n", 
                                                            track.Artist, 
                                                            track.Title, 
                                                            track.FilePath));
}

Track

public class Track
{
	public Guid Guid { get; set; }
	public string Artist { get; set; }
	public string Title { get; set; }
	public string FilePath { get; set; }
}

Guid

The unique identifier of the track. This must be unique when adding new tracks to the system.

Artist

The artist of the track.

Title

The title of the track.

FilePath

The path to the file on the file system.

TrackGroups

public abstract class TrackGroups
{
	public abstract void Add(TrackGroup group);
	public abstract void Edit(TrackGroup group);
	public abstract void Delete(TrackGroup group);
	public abstract IEnumerable<TrackGroup> Search(string search);
	public abstract IEnumerable<TrackGroup> Search(Predicate<TrackGroup> predicate);
	public abstract TrackGroup GetOne(string search);
	public abstract TrackGroup GetOne(Predicate<TrackGroup> predicate);
	public abstract IEnumerable<TrackGroup> GetAll();
}

Add()

Add a track group to the system. Currently, the only possible track group type is ListedTrackGroup. However, it is possible to workaround creating grouped track groups and filtered track groups by filtering and grouping tracks and adding them to a Listed Track Group.

Example
var listedTrackGroup = new ListedTrackGroup();
listedTrackGroup.Name = "Killers Songs";
listedTrackGroup.Tracks.AddRange(App.Tracks.Search("The Killers"));
App.TrackGroups.Add(listedTrackGroup);

Edit()

Edit a track group already existing in the system.

Example
using System.Linq;
...
var songsGroup = App.TrackGroups.Search("Songs").FirstOrDefault();
songsGroup.Name = "Music"; // rename the Songs group to "Music"
App.TrackGroups.Edit(songsGroup);

Delete

Delete a track group already existing in the system.

Example
using System.Linq;
...
var songsGroup = App.TrackGroups.Search("Songs").FirstOrDefault();
App.TrackGroups.Delete(songsGroup); // delete the Songs track group

Search

Find a track group by name or using a Predicate. A text string search will match the track group name. A predicate defines a set of criteria that a TrackGroup must match to be returned by the search.

Examples
var trackGroups = App.TrackGroups.Search("Songs"); // find all the track groups containing "Songs";
var trackGroups = App.TrackGroups.Search(g => g.Name == "Songs"); // find all track groups named exactly "Songs"

GetOne

Find a single track group by name or using a Predicate. This is the same as Search() above, but only returns one object.

Example
TrackGroup trackGroups = App.TrackGroups.GetOne("Songs"); // find all the first track group containing "Songs";

GetAll

Get all the track groups in the system. Useful for iterating over all the objects and dumping the track groups to file.

Example
// dump all the track group details to a file called groups.txt
foreach(TrackGroups trackGroup in App.TrackGroups.GetAll())
{
    System.IO.File.AppendAllText("groups.txt", string.Format("{0}\r\n", trackGroup.Name));
}

TrackGroup

public abstract class TrackGroup
{
	public Guid Guid { get; set; }
	public string Name { get; set; }
}

Guid

The unique identifier of the track group.

Name

The name of the track group.

ListedTrackGroup

public class ListedTrackGroup : TrackGroup
{
	public List<Track> Tracks { get; }
}

Tracks

The list of tracks associated with this track group.

Example

See TrackGroup Add() example.

PlayoutPattern

public abstract class PlayoutPattern
{
	public abstract void Set(IEnumerable<TrackGroup> trackGroups);
}

Set()

Sets the playout pattern used in Live-Assist mode.

Example
TrackGroup songsGroup = App.TrackGroups.Search("Songs").FirstOrDefault();
TrackGroup jinglesGroup = App.TrackGroups.Search("Jingles").FirstOrDefault();
List<TrackGroup> trackGroups = new List<TrackGroup>()
{
	songsGroup, songsGroup, jinglesGroup
};
App.PlayoutPattern.Set(trackGroups);

TrackQueueItem

public abstract class TrackQueueItem
{
	public abstract DateTime StartTime { get; }
	public abstract Track Track { get; }
}

StartTime

The time the queue item started or is due to start.

Track

The track the queue item represents.

Example

See GetQueueItems()

 

QuickCarts

public abstract class QuickCarts
{
	public abstract CartBasedMode DockedToBottom { get; }
	public abstract CartBasedMode Wall { get; }
}

DockedToBottom

Provides access to the QuickCarts that are docked to the bottom of the main interface.

Wall

Provides access to the QuickCarts that are on a separate window.

PlayoutMode

public enum PlayoutMode
{
	Manual,
	SemiAuto,
	Auto,
}

PlayerEventArgs

public abstract class PlayerEventArgs : EventArgs
{
	public abstract int Index { get; }
	public abstract Track Track { get; }
}

Index

The index (zero-based position) of the player that raised the event.

Track

The track currently loaded by the player.

Settings

public abstract class Settings
{
	public abstract void SetFadeTime(int milliseconds);
}

SetFadeTime()

Sets the fade time in milliseconds. This is the same as changing the fade time in File > Settings.

Examples
App.Settings.SetFadeTime(2000); // sets the fade time to 2 seconds (2000 milliseconds)
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox