Skip to content

SDK Reference

Introduction

This section provides a reference to all available Singular Graphic JavaScript API calls. For more in-depth instructions on implementation, see our Graphic SDK Developer Guide. To see example code for each API call, visit out Graphic SDK Demos and search by call.

Get started and Happy coding!

Getting Started

Include the Singular Graphic JavaScript library into your html code:

1
2
3
4
<head>
   <!-- Include the Singular Graphic JavaSrcipt library -->
   <script src="https://app.singular.live/libs/singularplayer/0.1.2/singularplayer.js"></script>
</head>

Add an iFrame to your html code for a non-interactive Singular Player instance:

1
2
3
4
<body>
    <!-- define iFrame for a non-interactive Singular Player Instance -->
    <iframe id="SingularPlayer" style='width:720px; height: 400px;' src="https://app.singular.live/singularplayer/client"></iframe>
</body>

Add an iFrame to your html code for an interactive Singular Player instance:

1
2
3
4
<body>
    <!-- define iFrame for an interactive Singular Player Instance -->
    <iframe id="SingularPlayer" style='width:720px; height: 400px;' src="https://app.singular.live/singularplayer/client?interactive=1"></iframe>
</body>

Create a Graphic Instance and load Composition

SingularPlayer(domId)

Creates a new SingularPlayer Instance on your web page and returns a handle to the SingularPlayer object.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
domId The target div that the SingularPlayer will replace String Yes

Return an object with the following:

ToDo: Add description of the singularPlayer object

DESCRIPTION TYPE
Handle to the SingularPlayer object object

loadComposition(compositionId, callback)

Load a composition specified by the compositionId into the SingularPlayer instance.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
compositionId id of the composition to load in the SingularPlayer Integer Yes
callback Callback function called when composition was loaded Function Yes

renderComposition(compositionObject, callback)

Load a composition specified by the compositionObject into the SingularPlayer instance.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
compositionObject JSON object containing the full description of the composition to load in the SingularPlayer JSON Yes
callback Callback function called when composition was loaded Function Yes

renderAppOutput(appId, output, callback)

Load the App Output specified by the appId and the output name into the SingularPlayer instance.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
appId The appId of the app to render in the SingularPlayer Integer Yes
output The name of the output of the app to render in the SingularPlayer.

Use null or undefined to pick the first output from the alphabetical order.

String Yes
callback Callback function called when composition was loaded Function Yes

Manage Listeners

addListener(event, callback)

Add a listener to the SingularPlayer object.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
event Add callback for type of event. String Yes
callback Callback function to add Function Yes

Type of listener events:

EVENT DESCRIPTION
state_changed Callback on composition state change.

{"compositionId":"2a948dc0-acd1-0db7-946b-2d5d2eadc379","state":"In","compositionName":"sub"}

error Callback on Error.

{"desc":"Error message"}

payload_changed Callback on payload change.

{"compId":"2a948dc0-acd1-0db7-946b-2d5d2eadc379","compositionId":"2a948dc0-acd1-0db7-946b-2d5d2eadc379","payload":{"subtext":"1234"},"compName":"sub","compositionName":"sub"}

datanode_payload_changed Callback on datanode payload change.

{"payload":{"Title":1531275447,"name":"khing2222","xxx":"xxxx"},"id":"-LE3kDQeLuvw7vFzYkaj","name":"khingDataNode"}

app_output_changed Internal use only
message Internal use only

removeListener(event, callback)

Remove listener from SingularPlayer object.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
event Remove callback of type of event. String Yes
callback Callback function to remove Function Yes

Manage Compositions

getCompositionInfo()

Get all details of the composition loaded into the SingularPlayer instance.

Return a JSON structure with an array of key and value pairs.

DESCRIPTION TYPE
key and value pairs in the format

[x: string]: any

JSON

getMainComposition()

Get the main compositin loaded into the SingularPlayer instance

Return the composition object in a JSON structure.

DESCRIPTION TYPE
composition object JSON

getCompositionById(compositionId)

Get the composition specified by the compositionId.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
compositionId id of the composition Integer Yes

Valid value types for the compositionId:

Value DESCRIPTION
compositionId == [number] return the subcomposition with the specified compositionId
compositionId == undefined return the main composition

Return the composition object in a JSON structure.

DESCRIPTION TYPE
composition object JSON

Manage and Control Composition Instances

id: compId

This is the id of the composition or subcomposition.
It is the same id that is passed to getSubcompositionById(compositionId)

Note:

This id is mainly used for debugging purposes.

jumpTo(animationState)

Jump to the specified animationState in the animation timeline.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
animationState state in the animation timeline String Yes

Valid values for the animationState:

Value DESCRIPTION
animationState = "In" Jump to animation state In - show all objects
animationState = "Out" Jump to animation state Out - hide all objects
animationState = "Out1" Jump to animation state Out1 - hide all objects
animationState = "Out2" Jump to animation state Out2 - hide all objects

Note:

The animation states Out1 and Out2 are only available when two independed timelines for the In and Out animations are activated!

playTo(animationState)

Play the animation from the current to the specified animationState.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
animationState state in the animation timeline String Yes

Valid values for the animationState:

Value DESCRIPTION
animationState = "In" Play animation to state In - show all objects
animationState = "Out" Play animation to state Out - hide all objects
animationState = "Out1" Play animation to state Out1 - hide all objects
animationState = "Out2" Play animation to state Out2 - hide all objects

Note:

The animation states Out1 and Out2 are only available when two independed timelines for the In and Out animations are activated!

seek(time)

Seek the animation timeline of the subcomposition instance to the specified time defined in [sec]. Seek shows the animation at any time also between animation states.

Note:

This function only supports animations with a single timeline

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
time state in the animation timeline String Yes

setPayload(payload)

Send data specified by payload to the composition.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
payload key and value pairs in the format

[x: string]: any

JSON Yes

getSubcompositionById(subCompId)

Get the subcomposition in the subcomposition instance specified by the compositionId.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
compositionId id of the composition Integer Yes

Valid value types for the compositionId:

Value DESCRIPTION
compositionId == [number] return the subcomposition with the specified compositionId
compositionId == undefined return the main composition

Return the composition object in a JSON structure.

DESCRIPTION TYPE
composition object JSON

getCompositionById(subCompId)

Get the composition in the subcomposition instance specified by the compositionId.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
compositionId id of the composition Integer Yes

Valid value types for the compositionId:

Value DESCRIPTION
compositionId == [number] return the subcomposition with the specified compositionId
compositionId == undefined return the main composition

Return the composition object in a JSON structure.

DESCRIPTION TYPE
composition object JSON

listSubcompositions()

List all subcompositions of the subcomposition instance.

Return an array:

DESCRIPTION TYPE
array of id and name pairs Array

getDataNodes()

Get all datanodes of the subcomposition instance.

Return a JSON structure:

DESCRIPTION TYPE
JSON structure of key and value pairs JSON

getModel()

Get the datanode model of the subcomposition instance. Use this information to create fill-in form UIs for the composition.

Return an array of models:

DESCRIPTION TYPE
Model e.g.

[{"defaultValue":"Default Text",
"id":"text",
"index":0,
"title":"text",
"type":"text"}]

JSON

getPayload()

Get payload of the subcomposition instance.

Return an array:

DESCRIPTION TYPE
array of key and value pairs Array

getPayload2()

Get payload of the subcomposition instance.

Return an object:

DESCRIPTION TYPE
JSON structure of key and value pairs JSON

getControlNode()

Get controlnode payload and model data of the subcomposition instance.

Return a controlnode object:

DESCRIPTION TYPE
controlnode object with payload and model data JSON

getState()

Get animation state of the subcomposition instance.

Return the animation state:

DESCRIPTION TYPE
In ... animation in state In - all objects visible String
Out ... animation in state Out - all objects invisible String
Out1 ... animation in state Out1 - all objects invisible String
Out2 ... animation in state Out2 - all objects invisible String

find(parentId, searchPath)

Find sub composition(s) in a relative searchPath in a parent composition.

ATTRIBUTE DESCRIPTION TYPE REQUIRED
parentId id of the parent composition String Yes
searchPath search path within the parent composition String Yes

Manage and Control Sequencer Instances

getSequencer()

Get the sequencer instance of the subcomposition instance

Return the sequencer instance object

DESCRIPTION TYPE
sequencer instance object JSON

setPayload(payload)

Set the sequencer payload.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
payload key and value pairs JSON Yes

Return:

DESCRIPTION TYPE
No value returned -

start()

Start playing the sequencer timeline.

Return:

DESCRIPTION TYPE
No value returned -

stop()

Stop playing the sequencer timeline.

Return:

DESCRIPTION TYPE
No value returned -

seek(time)

Seek the sequencer timeline of the subcomposition instance to the specified time defined in [sec].

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
time time [sec] in the sequencer timeline String Yes

setDuration(duration)

Set the duration of a sequence specified by duration in [sec].

ATTRIBUTE DESCRIPTION TYPE REQUIRED
duration duration in [sec] String Yes

Return:

DESCRIPTION TYPE
No value returned -

allSequencers.start()

Start playing all sequencer timelines.

Return:

DESCRIPTION TYPE
No value returned -

allSequencers.stop()

Stop playing all sequencer timelines.

Return:

DESCRIPTION TYPE
No value returned -

allSequencers.seek(time)

Seek all sequencer timelines of the composition instance to the specified time defined in [sec].

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
time time [sec] in the sequencer timeline String Yes

Find more documentation

  • Singular GraphicSDK Developer Guide: here...
  • Singular GraphicSDK Demos and Code Examples: here....

Getting Help