Skip to main content

API User Guide

Getting Access​

To utilise the Player API you will need an API Token. These can be obtained from https://dashboard.aimi.fm under the Player API tab. Multiple tokens can be created and each expires after 30 days. These access tokens can be exchanged for a session token whenever you wish to begin a new session.
The Aimi Player API Flow

Aimi Player generates endless streams of music for any situation across many different genres. The Aimi Player API allows you to interact with the stream in real time via Plans and other endpoints. Documentation for the endpoints is provided on the Endpoints tab of this page. This guide is intended to provide an overview for development with the API.

Creating a new stream​

To begin a new session, pass an API token obtained from the dashboard as a standard Bearer token in a request to the /new-stream Player API endpoint. You will receive a session token in response which is used for all other endpoints.

Connecting to the stream​

Once the session has been created, pass the session token to the /stream endpoint to create a low latency audio connection to the client. See this endpoint’s documentation for detailed information and links to example implementations.

Interacting with the stream​

Use the /playerstart endpoint to start Aimi Player. The style of audio played can be controlled by specifying a particular experienceid. These ids can be found by using the /genres endpoint or by liaising with your Aimi representative. Not all experienceids will offer the same amount of interactivity so it is highly recommended that you only use the experienceids given to you by Aimi. The player can be stopped using the /playerstop endpoint without ending the stream.

See the Endpoints tab for further controls.

Ending the stream​

To end your session, pass your session token as a standard Bearer token in a request to the /end-stream Player API endpoint at any point during the session. The session will expire automatically if this endpoint is not called - but the full duration of the session will be deducted from your API token’s credits.

Controlling the Music​

Introduction - The Plan

Almost all aspects of the music can be controlled by providing the stream with a ‘Plan’. A plan is a set of musical instructions which lays out what style of music should be played as well as detailed controls for tempo, arrangement and control of effects. A Plan is a JSON object. Here is an example of a simple Plan:

{
    "planDescriptors": {
        "style": "deepHouse",
        "tempo": 132
    },
    "sections": [
        {
            "displayName": "firstSection",
            "duration": 64,
            "groups": {
                "beats": {},
                "bass": {},
                "pads": {},
                "melody": {}
            }
        }
    ]
}

This example creates a single looping section with beats (drums), bass, pads and melody. You can expand on this by adding multiple sections, adjusting durations or swapping instruments. Here is a more complex example:

{
   "name": "testName",
   "planDescriptors": {
       "style": "deepHouse",
       "tempo": 130
   },
   "sections": [
       {
           "displayName": "firstSection",
           "duration": 16,
           "groups": {
               "beats": {},
               "bass": {}
           },
           "effects": {
               "filterACutoff": [
                   {
                       "groups": ["beats", "bass"],
                       "endVal": 20,
                   }
               ]
           }
       },

       {
           "displayName": "secondSection",
           "duration": 16,
           "groups": {
               "beats": {},
               "bass": {},
               "melody": {},
           },
           "effects": {
               "filterACutoff": [
                   {
                       "groups": ["beats", "bass"], 
                       "endVal": 5000,
                       "transitionTime": 4,
                       "offset": 8
                   }
               ]
           }
       }
   ]
}

In this example we have a Plan set to 130bpm with a style of deep house. It has two sections both with a duration of 16 beats each. The first section has two instruments (groups) while the second adds a third (melody). Additionally both sections take advantage of the range of effects available. “filterA” is by default set to be a highpass filter. In this example we are adjusting the cutoff point of that filter. In the first section we set the cutoff to 20Hz immediately at the start of the section. In the second section we ramp the cutoff point to 5000Hz over 4 beats starting 8 beats into the section. Both effect changes affect the groups beats and bass.

Available Groups

beats: drums, electronic and acoustic etc. bass: bass synth, bass guitar etc. harmony: synths, piano, guitar etc. Usually the basis for chordal movement. pads: synths, strings etc. Supporting melodic content. tops: hand percussion, auxiliary percussion, shakers etc. melody: synths, guitar, various lead instruments. fx: risers and transition sounds. Plays in between sections to transition from one to another. vocals: Vocal melodies.