User Tools

Site Tools


apiref

General


Performance(performancedata object)

Parameters

performanceData is optional, and can contain the following:

  • composer string, the composer's name. Default = “Unknown composer”
  • title string, the composition title. Default = “Untitled composition”
  • tempo int, beats per minute. Default = 60
  • duration int, the performance duration in milliseconds to be used referentially. Default = null
  • showNextEvent bool, whether performers get to see the next event. Default = true
  • progressBar bool, whether the event progress bar is shown. Default = true
  • eventCounter bool, whether the event number counter is shown. Default = true
  • throb bool, whether to pulse the screen in time with the tempo (and attempt dynamic matching with next event tempo). Default = false
  • throbNext bool, whether to pulse the next event preview. Default = true
  • throbAdapt bool, whether to dynamically interpolate tempo between events. Default=false
  • introductionText string, text to be shown to all performers when joining. Default = null

Properties

  • composer string,
  • title string,
  • tempo int
  • duration int
  • showNextEvent bool
  • progressBar bool
  • eventCounter bool
  • throb bool
  • throbAdapt bool
  • throbNext bool
  • introductionText string
  • running bool, whether the performance is in progress
  • time float, the runtime of the performance in milliseconds

Example

new Performance({composer:"Anonymous", title:"Fast piece", tempo:4});

Role(name string [null=auto assigned], data object)

Roles allow multiple performers to be grouped with the same events. data is optional and can contain any or all of the properties: key,instrument, clef, preamble, maxPerformers which have the same definition as the accessible properties (below) after construction .

Parameters

  • name string, the name of the role. If empty or null, it is automatically assigned as “Role x” where x is a sequential number.
  • data object, can contain:
    • key string, a reference for the role key. Default = null
    • instrument string, a reference for the role instrumentation. Default = null
    • clef string, a reference for the role clef. Default = null
    • preamble string, text shown to specifically to the role after selection and prior to the performance start. Default = null
    • maxPerformers int, the maximum number of individuals permitted to join the role. Default = 1

Properties

  • name string, the name of the role given when created
  • key var, the instrument key as specified in data
  • clef var, the clef as specified in data
  • preamble string, the preamble text as specified in data
  • maxPerformers int, the maximum number of individuals assignable to the role
  • totalEvents int, the determined number of events for the role upon pre-load analysis. This could be inaccurate for indeterminate scores and resultantly is provided as read/write so that it can be updated from the performance logic.
  • performedEvents array, a chronologically ordered collection of Event objects which have been performed by the role within the given performance.
  • performanceTime int, the number of milliseconds expected for the complete role performance
  • roleMembers array, a collection of Performer

Functions

  • eachPerformer (callback function)
    calls a function for each performer associated with the role, passing a Performer object to the function as the only argument.

Example

new Role("Bass",{maxPerformers:2});

—-

Events

If user variables are employed rather than the internal dfscore naming, or if the name of an event does not need to be know (for example, inline event creation), name can be provided as null in which case it is assigned a sequential identifier.

Common Parameters

The order of name and data can be interchanged.

  • name string, the name of the event, auto-assigned if null.
  • data object, optional, containing the following. These reflect parameters given in new Performance() and fallback to the default described in the Performance reference if not supplied.
    • tempo int, beats per minute.
    • showNextEvent bool, whether performers get to see the next event.
    • progressBar bool, whether the event progress bar is shown.
    • eventCounter bool, whether the event number counter is shown (if event number can be determined)
    • throb bool, whether to pulse the screen in time with the tempo (and attempt dynamic matching with next event tempo).
    • throbNext bool, whether to pulse the next event preview.
    • throbAdapt bool, whether to dynamically interpolated to the next event's tempo

Common Properties

If not specified, the definition is the same as the parameter definition above.

  • name string, the name of the event given when created or the auto-assigned name
  • type string, the type of event as specified by the constructor type
  • content mixed , the event content, contextual to the type of event (eg, innerHTML for HtmlEvent, text for TextEvent). For ScriptEvent, content is an array with index 0 being the initScript and index 1 the runScript.
  • showNextEvent bool
  • progressBar bool
  • eventCounter bool
  • throb bool
  • throbNext bool
  • tempo float
  • throbAdapt bool

TextEvent(text string, name string [null=auto assigned], data object)

Parameters

  • text string, the test to be displayed

Properties

  • content string, the text associated with the event

Example

new TextEvent("Hello world", "event1", { progressBar:false});

HtmlEvent(html string, name string [null=auto assigned], data object)

Parameters

  • html string, the HTML element(s)

Properties

  • content string, the html associated with the event

Example

new HtmlEvent("<h1>Hello<small>World</small></h1>", {throb: false});

ScoreEvent(score string, name string [null=auto assigned], data object)

Parameters

  • score string, the vexTab markup for rendering the score

Properties

  • content string, the vextab markup associated with the event

Example

new ScoreEvent("stave notation=true \
                              notes :8 t12p7/4 s5s3/4 :8 3s:16:5-7/5 :h p5/4", "scoreEvent1", {throbAdapt:true});

ImageEvent(imageName string, name string [null=auto assigned], data object)

Parameters

  • imageName string, the name of the image file relative to the composition package directory, with extension included (eg “img1.jpg”). Supported types depend on the browser but generally include jpg, gif, png and svg.

Properties

  • content string, the image name associated with the event

Example

new ImageEvent("hello.jpg");

ScriptEvent(initScript mixed, runScript mixed name string [null=auto assigned], data object)

Parameters

  • initScript mixed, the string containing the script to be evaluated when the event is cached on the client, or an actual function to be evaluated when the event is cached on the client. In both cases the variable context represents the display area and can be written to with standard javascript or jQuery methods (eg context.text(“test”); )
  • runScript mixed, the string containing the script to be evaluated when the event is performed on the client, or an actual function to be performed when the event is cached on the client. In both cases the variable context represents the display area and can be written to with standard javascript or jQuery methods (eg context.text(“test”); ). duration can be referenced in runScript to find out the duration of the current event in milliseconds.

Properties

  • content array, the initScript and runScript as strings. initScript is at index 0 and runScript is at index 1.

Example

new ScriptEvent(null,function(){
       context.text("Play for this many seconds: "+ duration/1000);
      }, "script name");

—-

Performer

A Performer is represented by an individual connection to the DFS server with a unique name supplied on login/joining. The Performer object cannot be constructed from the API but can be accessed through the containing role via roleMembers once the performer has logged in/joined.

Properties

  • name string, the name of the performer as given when joining/logging in
  • ip string, the ip address of the performer. May be v4 or v6 depending on interface config
  • superuser bool , whether this person is the administrator
  • performanceReady bool , whether the performer is ready to perform
  • performedEvents object, the events performed and associated acknowledgement/latency details

Example

var performer1_inRole1 = roles["Role 1"].roleMembers[0];
new TextEvent("Only " + performer1_inRole1.name + " should play", "conditionalevent");


Triggers

As with Events, the order of name and data can be interchanged.

KeyboardTrigger(role mixed, name string [null=auto assigned], data object)

Parameters

  • role string, or Role object, the role to associate the trigger with
  • name string, the name of the trigger
  • data object, the definition of the trigger
    • key string, the key to react to (dfscore detects either upper or lowercase).

Properties

  • active bool, whether the Trigger is active - defaults to false so must be turned on prior to usage.
  • triggered boolean, whether the condition of the Trigger has been met. If true when queried, this is reset to false.
  • data the data supplied to the trigger upon construction.

Example

new KeyboardTrigger(roles.Bass, "reactA", {key: "a"});

perform(role mixed, event mixed, duration mixed)

Instructs the role to perform an event for a specified duration in milliseconds.
role can be the name of a role, or a variable referencing the actual role object (eg roles.Lead )
event can be the name of an event as a string, or a variable referencing the actual event object (eg. events.ev1).
duration may be a numerical value or a reference to a trigger. If a trigger is used, the event will be held with no specific duration until the trigger condition is met.

Example

perform(roles.Bass, "event1", 5000);

delegate(role mixed, exec function)

Executes code specifically in the control thread of a role.
role can be the name of a role as a string or a variable referencing the actual role object (eg roles.Lead )

Example

delegate(roles.Bass, function(){
      performance.ourVariable = 99;
}

dftool

dftool.rand(param mixed, param int)

Depending on the argument type(s), a different result will be returned. Only one permutation requires the second argument to be given:

  • (array) random item from an array
  • (object) random property from an object
  • (int) random number between 0 and the int parameter
  • (int, int) random number between the two int parameters

Example

var time = dftool.rand(1000,2000);

global

global can be used to set and retrieve data between roles before or during performance time.

  • (function) executes the function pre-performance - ie an initialisation script
  • (string,object/mixed) saves an object named string
  • (string) retrieves an object named string

Accessing Performance objects

All constructors return themselves, but also add themselves to the relevant userspace object as follows, with their name as the key.

  • Role : roles
  • *Event : events
  • Trigger : triggers
  • Listener : listeners
  • Performer : performers

Note that depending on the choice of names for objects, the javascript reference may be altered.
For example, if you use a period ( . ) in an event name, it would cause problems with the containing object:
new TextEvent (“my.event”,“Lots of dots”); would have to be accessed as events[“my.event”] , not events.my.event . Spaces and other characters have to be treated the same.

apiref.txt · Last modified: 2015/07/15 17:18 by richard