Pedal PI - WebService - API documentation

API Endpoint
http://pedalpi.local:3000/v1

Pedal Pi - WebService is a Pedal Pi component that offers a Pedal Pi management over REST + WebSocket. This documentation describes the REST API.

Authentication

Authentication has two purposes: Control access and obtaining token request identifier

Control access

Not implemented

Token identifier

With a token identifier, it is possible to send changes if they are identified, so that no notifications of their own changes to WebSocket occur.

When a connection is established with http://pedalpi.local/ws, a TOKEN message ("type": "TOKEN") returns a uuid4 for the client.

{
  "value": "{token uuid4}",
  "type": "TOKEN"
}

It’s necessary that all requests add the following header parameter.

x-xsrf-token: {token uuid4}
GET http://pedalpi.local:3000/v1/ws
Requests200
Headers
Content-Type: application/json; charset=UTF-8
x-xsrf-token: {token uuid4}
Responses200
Headers
Content-Type: application/json; charset=UTF-8
Body
anything

Example request
GET/ws

It’s a example request for a random address

Plugins management

It’s possible obtains the Lv2Plugins data in a json format. Pedal Pi uses lilvlib for parse to json.

Plugins

GET http://pedalpi.local:3000/v1/plugins
Responses200
Headers
Content-Type: application/json; charset=UTF-8
Body
{
    "plugins": [
        /* Plugins list */
        {"presets": [], ...},
    ]
}

Plugins list
GET/plugins

Get all audio plugins installed

Reload plugins

PUT http://pedalpi.local:3000/v1/plugins/reload
Responses200400
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "status": "ok"
}
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "lilv not configured"
}

Reload plugins
PUT/plugins/reload

Reloads the lv2 plugins data.

To get the audio plugin metadata, you need to install lilv. Check the Lv2EffectBuilder.lv2_plugins_data() method documentation for more details on how to install.

If lilv is not installed, an error (400) is returned.

Plugin

GET http://pedalpi.local:3000/v1/plugin/http:/calf.sourceforge.net/plugins/MonoInput
Responses200400
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "label": "Calf Mono Input",
  "microVersion": 0,
  "bundles": [],
  "id": "56a8b5ad2f1d0e03d12a82fd",
  "stability": "experimental",
  "stable": false,
  "bundle_multi_plugins": true,
  "category": [
    "Utility"
  ],
  "binary": "calf.so",
  "thumbnail_available": false,
  "version": "0.0",
  "release_number": 2,
  "license": "http://usefulinc.com/doap/licenses/lgpl",
  "comment": "",
  "uri": "http://calf.sourceforge.net/plugins/MonoInput",
  "presets": [],
  "bundle_href": "http://api.dev.moddevices.com/v2/lv2/bundles/56a8b5ac2f1d0e03d12a82ad/",
  "screenshot_available": false,
  "author": {
    "name": "Calf Studio Gear / Markus Schmidt",
    "homepage": "http://calf-studio-gear.org",
    "email": ""
  },
  "minorVersion": 0,
  "name": "Calf Mono Input",
  "href": "http://api.dev.moddevices.com/v2/lv2/plugins/56a8b5ad2f1d0e03d12a82fd/",
  "ports": {
    "control": {
      "input": [
        {
          "scalePoints": [],
          "name": "Bypass",
          "rangeSteps": null,
          "symbol": "bypass",
          "designation": "",
          "shortName": "Bypass",
          "properties": [
            "hasStrictBounds",
            "toggled"
          ],
          "index": 3,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Input",
          "rangeSteps": null,
          "symbol": "level_in",
          "designation": "",
          "shortName": "Input",
          "properties": [],
          "index": 4,
          "ranges": {
            "minimum": 0.015625,
            "default": 1,
            "maximum": 64
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Output",
          "rangeSteps": null,
          "symbol": "level_out",
          "designation": "",
          "shortName": "Output",
          "properties": [],
          "index": 5,
          "ranges": {
            "minimum": 0.015625,
            "default": 1,
            "maximum": 64
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Balance",
          "rangeSteps": null,
          "symbol": "balance_out",
          "designation": "",
          "shortName": "Balance",
          "properties": [
            "hasStrictBounds"
          ],
          "index": 12,
          "ranges": {
            "minimum": -1,
            "default": 0,
            "maximum": 1
          },
          "units": {
            "label": "coefficient",
            "symbol": "*",
            "render": "* %f"
          }
        },
        {
          "scalePoints": [],
          "name": "Softclip",
          "rangeSteps": null,
          "symbol": "softclip",
          "designation": "",
          "shortName": "Softclip",
          "properties": [
            "toggled",
            "hasStrictBounds"
          ],
          "index": 13,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Mute L",
          "rangeSteps": null,
          "symbol": "mutel",
          "designation": "",
          "shortName": "Mute L",
          "properties": [
            "toggled",
            "hasStrictBounds"
          ],
          "index": 14,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Mute R",
          "rangeSteps": null,
          "symbol": "muter",
          "designation": "",
          "shortName": "Mute R",
          "properties": [
            "hasStrictBounds",
            "toggled"
          ],
          "index": 15,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Phase L",
          "rangeSteps": null,
          "symbol": "phasel",
          "designation": "",
          "shortName": "Phase L",
          "properties": [
            "hasStrictBounds",
            "toggled"
          ],
          "index": 16,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Phase R",
          "rangeSteps": null,
          "symbol": "phaser",
          "designation": "",
          "shortName": "Phase R",
          "properties": [
            "hasStrictBounds",
            "toggled"
          ],
          "index": 17,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Delay",
          "rangeSteps": null,
          "symbol": "delay",
          "designation": "",
          "shortName": "Delay",
          "properties": [
            "hasStrictBounds"
          ],
          "index": 18,
          "ranges": {
            "minimum": -20,
            "default": 0,
            "maximum": 20
          },
          "units": {
            "label": "milliseconds",
            "symbol": "ms",
            "render": "%f ms"
          }
        },
        {
          "scalePoints": [],
          "name": "Stereo Base",
          "rangeSteps": null,
          "symbol": "stereo_base",
          "designation": "",
          "shortName": "Stereo Base",
          "properties": [],
          "index": 19,
          "ranges": {
            "minimum": -1,
            "default": 0,
            "maximum": 1
          },
          "units": {
            "label": "coefficient",
            "symbol": "*",
            "render": "* %f"
          }
        },
        {
          "scalePoints": [],
          "name": "Stereo Phase",
          "rangeSteps": null,
          "symbol": "stereo_phase",
          "designation": "",
          "shortName": "Stereo Phase",
          "properties": [
            "hasStrictBounds"
          ],
          "index": 20,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 360
          },
          "units": {
            "label": "degrees",
            "symbol": "deg",
            "render": "%f deg"
          }
        },
        {
          "scalePoints": [],
          "name": "S/C Level",
          "rangeSteps": null,
          "symbol": "sc_level",
          "designation": "",
          "shortName": "S/C Level",
          "properties": [
            "logarithmic"
          ],
          "index": 21,
          "ranges": {
            "minimum": 1,
            "default": 1,
            "maximum": 100
          },
          "units": {
            "label": "coefficient",
            "symbol": "*",
            "render": "* %f"
          }
        }
      ],
      "output": [
        {
          "scalePoints": [],
          "name": "Input",
          "rangeSteps": null,
          "symbol": "meter_in",
          "designation": "",
          "shortName": "Input",
          "properties": [
            "hasStrictBounds",
            "connectionOptional"
          ],
          "index": 6,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Output L",
          "rangeSteps": null,
          "symbol": "meter_outL",
          "designation": "",
          "shortName": "Output L",
          "properties": [
            "hasStrictBounds",
            "connectionOptional"
          ],
          "index": 7,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Output R",
          "rangeSteps": null,
          "symbol": "meter_outR",
          "designation": "",
          "shortName": "Output R",
          "properties": [
            "hasStrictBounds",
            "connectionOptional"
          ],
          "index": 8,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "0dB-In",
          "rangeSteps": null,
          "symbol": "clip_in",
          "designation": "",
          "shortName": "0dB-In",
          "properties": [
            "hasStrictBounds",
            "connectionOptional"
          ],
          "index": 9,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "0dB-OutL",
          "rangeSteps": null,
          "symbol": "clip_outL",
          "designation": "",
          "shortName": "0dB-OutL",
          "properties": [
            "hasStrictBounds",
            "connectionOptional"
          ],
          "index": 10,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "0dB-OutR",
          "rangeSteps": null,
          "symbol": "clip_outR",
          "designation": "",
          "shortName": "0dB-OutR",
          "properties": [
            "hasStrictBounds",
            "connectionOptional"
          ],
          "index": 11,
          "ranges": {
            "minimum": 0,
            "default": 0,
            "maximum": 1
          },
          "units": {}
        }
      ]
    },
    "audio": {
      "input": [
        {
          "scalePoints": [],
          "name": "In L",
          "rangeSteps": null,
          "symbol": "in_l",
          "designation": "http://lv2plug.in/ns/ext/port-groups#left",
          "shortName": "In L",
          "properties": [],
          "index": 0,
          "ranges": {},
          "units": {}
        }
      ],
      "output": [
        {
          "scalePoints": [],
          "name": "Out L",
          "rangeSteps": null,
          "symbol": "out_l",
          "designation": "http://lv2plug.in/ns/ext/port-groups#left",
          "shortName": "Out L",
          "properties": [],
          "index": 1,
          "ranges": {},
          "units": {}
        },
        {
          "scalePoints": [],
          "name": "Out R",
          "rangeSteps": null,
          "symbol": "out_r",
          "designation": "http://lv2plug.in/ns/ext/port-groups#right",
          "shortName": "Out R",
          "properties": [],
          "index": 2,
          "ranges": {},
          "units": {}
        }
      ]
    },
    "midi": {
      "input": [],
      "output": []
    }
  },
  "bundle_id": "56a8b5ac2f1d0e03d12a82ad",
  "bundle_name": "calf-bad.lv2",
  "gui": {},
  "brand": "Calf"
}
Schema
Not defined
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Plugin \"https://github.com/ninodewit/SHIRO-Plugins/plugins/larynx\" not installed"
}

Plugin data
GET/plugin/{uri}

Get a specific audio plugin json by uri identifier.

Some audio plugins have their uri containing #. To get the plugin data, you need to replace # with %23.

Example:

Replace

plugin/http://guitarix.sourceforge.net/plugins/gx_redeye#chump

with

plugin/http://guitarix.sourceforge.net/plugins/gx_redeye%23chump
URI Parameters
HideShow
uri
string (required) Example: http://calf.sourceforge.net/plugins/MonoInput

The plugin URI

Banks management

Manages the banks data.

Banks

GET http://pedalpi.local:3000/v1/banks
Responses200
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "banks": {
    "0": {"index": 0, ...},
    "1": {"index": 0, ...}
  }
}

List banks
GET/banks

Get all banks

Bank management

Bank

Manages a bank: creates a new, update, get the bank data or removes it.

POST http://pedalpi.local:3000/v1/bank
Requestsexample 1
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "index": -1,
  "name": "My new bank",
  "pedalboards": [
    {
      "name": "The awesome pedalboard",
      "effects": [],
      "connections": [],
      "data": {}
    }
  ]
}
Responses200
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "index": 2
}

Save new bank
POST/bank

Save a new bank.

Send the new bank with the index: -1. The response returns the bank index.

It’s necessary updates the (client) bank data with the returned index.

Manages a bank by index

GET http://pedalpi.local:3000/v1/bank/1
Responses200400
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "index": 1,
  "pedalboards": [
    {
      "connections": [
        {
          "input": {
            "index": 0,
            "effect": 0,
            "symbol": "in"
          },
          "output": {
            "index": 0,
            "symbol": "capture_1"
          }
        },
        {
          "input": {
            "index": 0,
            "symbol": "playback_1"
          },
          "output": {
            "index": 1,
            "effect": 0,
            "symbol": "out"
          }
        }
      ],
      "data": {
        "pedalpi-apk": {
          "effectPositions": [
            {
              "y": 91.4995002746582,
              "x": 159.74801635742188
            }
          ]
        }
      },
      "effects": [
        {
          "active": true,
          "plugin": "http://drobilla.net/plugins/fomp/cs_chorus1",
          "technology": "lv2",
          "params": [
            {
              "index": 2,
              "value": 7.5,
              "minimum": 0,
              "maximum": 30,
              "symbol": "delay"
            },
            {
              "index": 3,
              "value": 0.20000000298023224,
              "minimum": 0.003000000026077032,
              "maximum": 10,
              "symbol": "mod_freq_1"
            },
            {
              "index": 4,
              "value": 2.5,
              "minimum": 0,
              "maximum": 10,
              "symbol": "mod_amp_1"
            },
            {
              "index": 5,
              "value": 0.800000011920929,
              "minimum": 0.009999999776482582,
              "maximum": 30,
              "symbol": "mod_freq_2"
            },
            {
              "index": 6,
              "value": 0.75,
              "minimum": 0,
              "maximum": 3,
              "symbol": "mod_amp_2"
            }
          ]
        }
      ],
      "name": "Empty pedalboard"
    }
  ],
  "name": "My awesome bank"
}
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Invalid index"
}

Get by index
GET/bank/{bank_index}

Request a bank data with the bank index.

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

PUT http://pedalpi.local:3000/v1/bank/1
Requestsexample 1
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "index": -1,
  "name": "My new bank",
  "pedalboards": [
    {
      "name": "The awesome pedalboard",
      "effects": [],
      "connections": [],
      "data": {}
    }
  ]
}
Responses200400
Headers
Content-Type: application/json; charset=UTF-8
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Invalid index"
}

Update by index
PUT/bank/{bank_index}

Update a bank

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

DELETE http://pedalpi.local:3000/v1/bank/1
Responses200400
This response has no content.
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Invalid index"
}

Delete by index
DELETE/bank/{bank_index}

Delete a bank

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

Pedalboard management

Manages a pedalboard: creates a new, update, get the pedalboard data or removes it.

Pedalboard

POST http://pedalpi.local:3000/v1/bank/1/pedalboard
Requests201
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "name": "My new pedalboard",
  "effects": [],
  "connections": [],
  "data": {}
}
Responses200
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "index": 1
}

Save new pedalboard
POST/bank/{bank_index}/pedalboard

Save a new pedalboard.

The pedalboard position in bank pedalboards list is returned

The pedalboard does not have an identifier, the returned index is only for listing and sorting purpose.

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

Manages a pedalboard by index position

GET http://pedalpi.local:3000/v1/bank/1/pedalboard/3
Responses200400
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "name": "My new pedalboard",
  "effects": [],
  "connections": [],
  "data": {}
}
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Invalid index"
}

Get by index position
GET/bank/{bank_index}/pedalboard/{pedalboard_index}

Request a pedalboard data with the your index (pedalboard position in bank pedalboards list).

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

PUT http://pedalpi.local:3000/v1/bank/1/pedalboard/3
Requests200
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "name": "My new pedalboard",
  "effects": [],
  "connections": [],
  "data": {}
}
Responses200400
This response has no content.
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Invalid index"
}

Update by index position
PUT/bank/{bank_index}/pedalboard/{pedalboard_index}

Update a pedalboard

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

DELETE http://pedalpi.local:3000/v1/bank/1/pedalboard/3
Responses200400
This response has no content.
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Invalid index"
}

Delete by index position
DELETE/bank/{bank_index}/pedalboard/{pedalboard_index}

Delete a pedalboard

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

Pedalboard Data management

Manages a custom data for a specified pedalboard.

This feature allows multiple clients to add their data to a pedalboard.

For secure use, you must choose a unique key identifier for the customer so that other customers do not change the data.

For example, Pedal Pi - Apk uses the pedalpi-apk key.

The data persisted has been added in pedalboard:

{
  "name": "My pedalboard",
  "connections": [],
  "effects": [
    {
      "technology": "lv2",
      "plugin": "http://drobilla.net/plugins/fomp/cs_chorus1",
      "other informations": "yes",
    }
  ],
  "data": {
    "pedalpi-apk": {
      "effectPositions": [
        {
          "x": 137.3348846435547,
          "y": 88.69785690307617
        }
      ]
    }
  }
}

Manages by key

GET http://pedalpi.local:3000/v1/bank/1/pedalboard/3/data/pedalpi-apk
Requests200200
Headers
Content-Type: application/json; charset=UTF-8
Responses200
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "effectPositions": [
    {
      "x": 159.74801635742188,
      "y": 91.4995002746582
    }
  ]
}
Headers
Content-Type: application/json; charset=UTF-8
Responses200
Headers
Content-Type: application/json; charset=UTF-8
Body
{}

Get by key
GET/bank/{bank_index}/pedalboard/{pedalboard_index}/data/{key}

Request a param data with the your position

If the request with a key that not data has been not persisted yet, the response returns a empty json object:

{}
URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

key
string (required) Example: pedalpi-apk

Key identifier for data

PUT http://pedalpi.local:3000/v1/bank/1/pedalboard/3/data/pedalpi-apk
Requests200
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "effectPositions": [
    {
      "x": 159.74801635742188,
      "y": 91.4995002746582
    }
  ]
}
Responses200
This response has no content.

Update by key
PUT/bank/{bank_index}/pedalboard/{pedalboard_index}/data/{key}

Update the data for a pedalboard

If any data has been not persisted yet, uses PUT too instread POST method (POST method has been not implemented)

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

key
string (required) Example: pedalpi-apk

Key identifier for data

Effect management

Manages a effect: creates a new, get the effect data or removes it.

For update effect data, view current toggle status effect and update param data.

Effect data

POST http://pedalpi.local:3000/v1/bank/1/pedalboard/3/effect
Requests201
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "active": true,
  "params": [
    {
      "index": 2,
      "maximum": 30,
      "value": 7.5,
      "symbol": "delay",
      "minimum": 0
    },
    {
      "index": 3,
      "maximum": 10,
      "value": 0.20000000298023224,
      "symbol": "mod_freq_1",
      "minimum": 0.003000000026077032
    },
    {
      "index": 4,
      "maximum": 10,
      "value": 2.5,
      "symbol": "mod_amp_1",
      "minimum": 0
    },
    {
      "index": 5,
      "maximum": 30,
      "value": 0.800000011920929,
      "symbol": "mod_freq_2",
      "minimum": 0.009999999776482582
    },
    {
      "index": 6,
      "maximum": 3,
      "value": 0.75,
      "symbol": "mod_amp_2",
      "minimum": 0
    }
  ],
  "plugin": "http://drobilla.net/plugins/fomp/cs_chorus1",
  "technology": "lv2"
}
Responses200
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "index": 1
}

Save new effect
POST/bank/{bank_index}/pedalboard/{pedalboard_index}/effect

Save a new effect.

The effect position in pedalboard effects list is returned.

The effect does not have an identifier, the returned index is only for listing and sorting purpose.

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard index (position)

Manages a effect by index position

GET http://pedalpi.local:3000/v1/bank/1/pedalboard/3/effect/2
Responses200400
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "active": true,
  "params": [
    {
      "index": 2,
      "maximum": 30,
      "value": 7.5,
      "symbol": "delay",
      "minimum": 0
    },
    {
      "index": 3,
      "maximum": 10,
      "value": 0.20000000298023224,
      "symbol": "mod_freq_1",
      "minimum": 0.003000000026077032
    },
    {
      "index": 4,
      "maximum": 10,
      "value": 2.5,
      "symbol": "mod_amp_1",
      "minimum": 0
    },
    {
      "index": 5,
      "maximum": 30,
      "value": 0.800000011920929,
      "symbol": "mod_freq_2",
      "minimum": 0.009999999776482582
    },
    {
      "index": 6,
      "maximum": 3,
      "value": 0.75,
      "symbol": "mod_amp_2",
      "minimum": 0
    }
  ],
  "plugin": "http://drobilla.net/plugins/fomp/cs_chorus1",
  "technology": "lv2"
}
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Invalid index"
}

Get by index position
GET/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}

Request a effect data with the your index (effect position in pedalboard effects list).

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

effect_index
number (required) Example: 2

Effect position in pedalboard effects list

DELETE http://pedalpi.local:3000/v1/bank/1/pedalboard/3/effect/2
Responses200400
This response has no content.
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Invalid index"
}

Delete by index position
DELETE/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}

Delete a effect

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

effect_index
number (required) Example: 2

Effect position in pedalboard effects list

Param management

Manages a param: update and retrive the value.

Manages a param by index position

Params contains a index attribute, but the requests needs the index position in params list.

GET http://pedalpi.local:3000/v1/bank/1/pedalboard/3/effect/2/param/0
Responses200400
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "maximum": 30,
  "minimum": 0,
  "value": 17,
  "symbol": "delay",
  "index": 2
}
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Invalid index"
}

Get by index position
GET/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}/param/{param_index}

Request a param data with the your position

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

effect_index
number (required) Example: 2

Effect position in pedalboard effects list

param_index
number (required) Example: 0

Param position in effect params list

PUT http://pedalpi.local:3000/v1/bank/1/pedalboard/3/effect/2/param/0
Requests200
Headers
Content-Type: text/plain
Body
1.1901190476159431
Responses200400
This response has no content.
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "error": "Invalid index"
}

Update by index position
PUT/bank/{bank_index}/pedalboard/{pedalboard_index}/effect/{effect_index}/param/{param_index}

Update a pedalboard

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

effect_index
number (required) Example: 2

Effect position in pedalboard effects list

param_index
number (required) Example: 0

Param position in effect params list

Effect connections management

Connect and disconnect effects.

Manages by key

POST http://pedalpi.local:3000/v1/bank/1/pedalboard/3/connect
Requestsexample 1example 2
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "output": {
    "effect": 0,
    "symbol": "out",
    "index": 1
  },
  "input": {
    "symbol": "playback_2",
    "index": 1
  }
}
Responses200
This response has no content.
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "output": {
    "effect": 0,
    "symbol": "out",
    "index": 1
  },
  "input": {
    "effect": 1,
    "symbol": "in_l",
    "index": 0
  }
}
Responses200
This response has no content.

Add a new connection
POST/bank/{bank_index}/pedalboard/{pedalboard_index}/connect

Add a new connection between pedalboards

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

PUT http://pedalpi.local:3000/v1/bank/1/pedalboard/3/connect
Requestsexample 1example 2
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "output": {
    "effect": 0,
    "symbol": "out",
    "index": 1
  },
  "input": {
    "symbol": "playback_2",
    "index": 1
  }
}
Responses200
This response has no content.
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "output": {
    "effect": 0,
    "symbol": "out",
    "index": 1
  },
  "input": {
    "effect": 1,
    "symbol": "in_l",
    "index": 0
  }
}
Responses200
This response has no content.

Disconnect effects
PUT/bank/{bank_index}/pedalboard/{pedalboard_index}/connect

Disconnect the specified connection

Is used PUT instread DELETE because DELETE don’t accepts body data

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

Current management

Provides easy access to current pedalboard settings

Retrieve current

GET http://pedalpi.local:3000/v1/current
Responses200
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "bank": 1,
  "pedalboard": 0
}

Current index
GET/current

Returns the current pedalboard index and your bank index.

Manages the current effect

GET http://pedalpi.local:3000/v1/current/data
Responses200
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "bank": {
    "index": 2,
    "name": "Rock 80's",
    "pedalboards": [
      {
        "name": "Go go punk",
        "connections": [],
        "data": {},
        "effects": []
      }
    ]
  },
  "pedalboard": 0
}

Current data
GET/current/data

Returns the json data of the bank of the current pedalboard.

Manages the current pedalboard

PUT http://pedalpi.local:3000/v1/current/bank/1/pedalboard/3
Responses200
Headers
Content-Type: application/json; charset=UTF-8

Set current pedalboard
PUT/current/bank/{bank_index}/pedalboard/{pedalboard_index}

The the specified pedalboard for the current. The audio processing will be setted for the pedalboard configuration (adding effects and your relationships).

URI Parameters
HideShow
bank_index
number (required) Example: 1

Bank index

pedalboard_index
number (required) Example: 3

Pedalboard position in bank pedalboards list

Maneges effect status of the current pedalboard

PUT http://pedalpi.local:3000/v1/current/effect/2
Responses200
Headers
Content-Type: application/json; charset=UTF-8

Toggle effect status
PUT/current/effect/{effect_index}

Toggle the status of a effect of the current pedalboard.

Toggle status effect: Changes the status active → bypass or the reverse (bypass → active) for a effect loaded.

URI Parameters
HideShow
effect_index
number (required) Example: 2

Effect position in pedalboard effects list

Move

Move Bank

Use it to changes the order of the banks in banks list.

PUT http://pedalpi.local:3000/v1/move/bank/3/to/2
Requestsexample 1
Headers
Content-Type: application/json; charset=UTF-8
Responses200
Headers
Content-Type: application/json; charset=UTF-8

Change banks order
PUT/move/bank/{from_index}/to/{to_index}

Change the position of a bank in banks list

URI Parameters
HideShow
from_index
number (required) Example: 3

Actual bank position in banks list

to_index
number (required) Example: 2

New bank position in banks list

Move Pedalboard

Use it to changes the order of the pedalboards of a bank.

PUT http://pedalpi.local:3000/v1/move/bank/1/pedalboard/3/to/2
Requestsexample 1
Headers
Content-Type: application/json; charset=UTF-8
Responses200
Headers
Content-Type: application/json; charset=UTF-8

Change order of a pedalboard in your bank
PUT/move/bank/{bank_index}/pedalboard/{from_index}/to/{to_index}

Change the position of a pedalboard in your bank

URI Parameters
HideShow
bank_index
number (required) Example: 1

Index of Bank that contains the pedalboard

from_index
number (required) Example: 3

Actual pedalboard position in bank pedalboards list

to_index
number (required) Example: 2

New pedalboard position in bank pedalboards list

Configurations

Manages Pedal Pi configurations

Device Name

GET http://pedalpi.local:3000/v1/configurations/device_name
Requestsexample 1
Headers
Content-Type: application/json; charset=UTF-8
Responses200
This response has no content.

Get device name (zeroconf)
GET/configurations/device_name

Get the device name that will appear in a search performed by zeroconf.

Set Device Name

PUT http://pedalpi.local:3000/v1/configurations/device_name/Paulo - Pedal Pi
Requestsexample 1
Headers
Content-Type: application/json; charset=UTF-8
Responses200
This response has no content.

Set the device name (zeroconf)
PUT/configurations/device_name/{new_name}

Change the device name that will appear in a search performed by zeroconf.

URI Parameters
HideShow
new_name
string (required) Example: Paulo - Pedal Pi

New device name

Component data

In addition to the possibility of persisting additional data for a particular pedalboard, it is possible to persist isolated data, that is, they do not share the same storage space with pedalboards.

Manage data

Access to the data is through a key. This key must be unique: more than one component using the same key will result in the same storage space for both.

It is expected, although not mandatory, that data from a component using this API have a unique key.

GET http://pedalpi.local:3000/v1/data/MyAwesomeComponent
Requestsexample 1No data previously saved
Headers
Content-Type: application/json; charset=UTF-8
Responses200
Body
{
  "a key": "a value"
}
Headers
Content-Type: application/json; charset=UTF-8
Responses200
Body
{}

Get component data
GET/data/{key}

Get the current data persisted for the informed key. If any data has previously persisted, returns a empty dict ({}).

URI Parameters
HideShow
key
string (required) Example: MyAwesomeComponent

Data component identifier. In format [a-zA-Z-0-9]+

PUT http://pedalpi.local:3000/v1/data/MyAwesomeComponent
Requestsexample 1
Headers
Content-Type: application/json; charset=UTF-8
Body
{"current-data": {"name": "test"}, {"value": [1, 2, 3]}}
Responses200
This response has no content.

Set component data
PUT/data/{key}

Persists a data for the informed key.

All current content is replaced by new.

When adding a new data, remember to stick with what has already been persisted.

URI Parameters
HideShow
key
string (required) Example: MyAwesomeComponent

Data component identifier. In format [a-zA-Z-0-9]+

DELETE http://pedalpi.local:3000/v1/data/MyAwesomeComponent
Requestsexample 1
Headers
Content-Type: application/json; charset=UTF-8
Responses200
This response has no content.

Clear component data
DELETE/data/{key}

Removes the current data persisted for the informed key.

Be cautious and do not erase data from other components that you are not managing.

URI Parameters
HideShow
key
string (required) Example: MyAwesomeComponent

Data component identifier. In format [a-zA-Z-0-9]+

WebSocket

Pedal Pi - WebService uses WebSockets to receive notification of changes made by other clients. For example, consider a Pedal Pi configured with the Raspberry-P0 and WebSocket components, when the user presses a button to change the current pedalboard, WebService clients will be notified that the status of the application has changed via their WebSocket connections.

In order for a client to not receive notifications of state changes made by the client itself, TOKEN identifier must be passed in the header.

WebSocket notification messages

Notification messages have a type field that determines the type of notification. EFFECT-TOGGLE, for example, informs that the notification refers to changing the current state of an effect (whether it is active or not).

Some message types have an updateType field to tell you what type of update occurred. The accepted values ​​for updateType are CREATED, UPDATED and DELETED. A type=CONNECTION message with updateType=DELETED indicates that a connection (which is described in the other fields of the message) has been removed.

For implementation details, check updates_observer_socket.py.

Notification on_current_pedalboard_changed

  • Parameters:

    • type: string - "CURRENT"
    • bank: number - Bank index
    • pedalboard: number - Pedalboard index
    • value: object - Current pedalboard data

  • Example:

    {
   "type":"CURRENT",
   "bank":0,
   "pedalboard":3,
   "value":{
      "data":{},
      "effects":[
         {
            "technology":"lv2",
            "active":true,
            "plugin":"http://calf.sourceforge.net/plugins/ReverseDelay",
            "params":[
               {
                  "value":32.142857142857146,
                  "maximum":300,
                  "minimum":30,
                  "symbol":"bpm",
                  "index":4
               },
               {
                  "value":1,
                  "maximum":300,
                  "minimum":1,
                  "symbol":"bpm_host",
                  "index":5
               },
               {
                  "value":1.0714285714285714,
                  "maximum":16,
                  "minimum":1,
                  "symbol":"subdiv",
                  "index":6
               },
               {
                  "value":5,
                  "maximum":16,
                  "minimum":1,
                  "symbol":"time_l",
                  "index":7
               },
               {
                  "value":5,
                  "maximum":16,
                  "minimum":1,
                  "symbol":"time_r",
                  "index":8
               },
               {
                  "value":0.5,
                  "maximum":1,
                  "minimum":0,
                  "symbol":"feedback",
                  "index":9
               },
               {
                  "value":0,
                  "maximum":1,
                  "minimum":-1,
                  "symbol":"amount",
                  "index":10
               },
               {
                  "value":0,
                  "maximum":1,
                  "minimum":0,
                  "symbol":"width",
                  "index":11
               },
               {
                  "value":0,
                  "maximum":1,
                  "minimum":0,
                  "symbol":"sync",
                  "index":12
               },
               {
                  "value":0,
                  "maximum":1,
                  "minimum":0,
                  "symbol":"reset",
                  "index":15
               },
               {
                  "value":0.40476190476190477,
                  "maximum":1,
                  "minimum":0,
                  "symbol":"window",
                  "index":16
               }
            ]
         }
      ],
      "name":"hehueuhes ea",
      "connections":[
         {
            "input":{
               "effect":0,
               "symbol":"in_l",
               "index":0
            },
            "output":{
               "symbol":"capture_1",
               "index":0
            }
         },
         {
            "input":{
               "symbol":"playback_1",
               "index":0
            },
            "output":{
               "effect":0,
               "symbol":"out_l",
               "index":2
            }
         }
      ]
   }
}

Notification on_bank_updated

  • Parameters:

    • type: string - "BANK"
    • updateType: enum[string] - (CREATED | UPDATED | DELETED)
    • bank: number - Bank index
    • value: object - Bank on which the notification refers

  • Example:

    {
  "type":"BANK",
  "updateType":"DELETED",
  "bank":3,
   "value":{
      "name":"My bank",
      "pedalboards":[
         {
            "data":{

            },
            "effects":[

            ],
            "name":"Empty pedalboard",
            "connections":[
               {
                  "input":{
                     "symbol":"playback_1",
                     "index":0
                  },
                  "output":{
                     "symbol":"capture_1",
                     "index":0
                  }
               }
            ]
         }
      ],
      "index":3
   }
}

Notification on_pedalboard_updated

  • Parameters:

    • type: string - "PEDALBOARD"
    • updateType: enum[string] - (CREATED | UPDATED | DELETED)
    • bank: number - Bank index
    • pedalboard: number - Pedalboard index
    • value: object - Pedalboard on which the notification refers

  • Example:

    {
  "type":"PEDALBOARD",
  "updateType":"UPDATED",
  "bank":2,
  "pedalboard":0,
  "value":{
      "data":{
         "pedalpi-apk":{
            "effectPositions":[

            ]
         }
      },
      "effects":[

      ],
      "name":"Guitar hero",
      "connections":[
         {
            "input":{
               "symbol":"playback_1",
               "index":0
            },
            "output":{
               "symbol":"capture_1",
               "index":0
            }
         }
      ]
   }
}

Notification on_effect_updated

  • Parameters:

    • type: string - "EFFECT"
    • updateType: enum[string] - (CREATED | UPDATED | DELETED)
    • bank: number - Bank index
    • pedalboard: number - Pedalboard index
    • effect: number - Effect index
    • value: object - Effect on which the notification refers

  • Example:

    {
   "type":"EFFECT",
   "updateType":"CREATED",
   "bank":2,
   "pedalboard":0,
   "effect":3,
   "value":{
      "technology":"lv2",
      "active":true,
      "plugin":"http://guitarix.sourceforge.net/plugins/gx_chorus_stereo#_chorus_stereo",
      "params":[
         {
            "value":0.5,
            "maximum":1,
            "minimum":0,
            "symbol":"level",
            "index":0
         },
         {
            "value":0.019999999552965164,
            "maximum":0.20000000298023224,
            "minimum":0,
            "symbol":"delay",
            "index":1
         },
         {
            "value":0.019999999552965164,
            "maximum":1,
            "minimum":0,
            "symbol":"depth",
            "index":2
         },
         {
            "value":3,
            "maximum":10,
            "minimum":0.10000000149011612,
            "symbol":"freq",
            "index":3
         }
      ],
      "pluginData":{
         "presets":[

         ],
         "comment":"\n\n\"In music, a chorus effect (sometimes chorusing or chorused effect) occurs when individual sounds with roughly the same timbre and nearly (but never exactly) the same pitch converge and are perceived as one. While similar sounds coming from multiple sources can occur naturally (as in the case of a choir or string orchestra), it can also be simulated using an electronic effects unit or signal processing device.\" Wikipedia\n\n*Unofficial documentation\n\nsource: http://en.wikipedia.org/wiki/Chorus_effect\n\n",
         "stability":"testing",
         "stable":false,
         "ports":{
            "audio":{
               "input":[
                  {
                     "units":{

                     },
                     "rangeSteps":null,
                     "properties":[

                     ],
                     "shortName":"In",
                     "designation":"",
                     "ranges":{

                     },
                     "name":"In",
                     "scalePoints":[

                     ],
                     "symbol":"in",
                     "index":6
                  },
                  {
                     "units":{

                     },
                     "rangeSteps":null,
                     "properties":[

                     ],
                     "shortName":"In1",
                     "designation":"",
                     "ranges":{

                     },
                     "name":"In1",
                     "scalePoints":[

                     ],
                     "symbol":"in1",
                     "index":7
                  }
               ],
               "output":[
                  {
                     "units":{

                     },
                     "rangeSteps":null,
                     "properties":[

                     ],
                     "shortName":"Out",
                     "designation":"",
                     "ranges":{

                     },
                     "name":"Out",
                     "scalePoints":[

                     ],
                     "symbol":"out",
                     "index":4
                  },
                  {
                     "units":{

                     },
                     "rangeSteps":null,
                     "properties":[

                     ],
                     "shortName":"Out1",
                     "designation":"",
                     "ranges":{

                     },
                     "name":"Out1",
                     "scalePoints":[

                     ],
                     "symbol":"out1",
                     "index":5
                  }
               ]
            },
            "control":{
               "input":[
                  {
                     "units":{

                     },
                     "rangeSteps":null,
                     "properties":[

                     ],
                     "shortName":"Level",
                     "designation":"",
                     "ranges":{
                        "maximum":1,
                        "minimum":0,
                        "default":0.5
                     },
                     "name":"Level",
                     "scalePoints":[

                     ],
                     "symbol":"level",
                     "index":0
                  },
                  {
                     "units":{

                     },
                     "rangeSteps":null,
                     "properties":[

                     ],
                     "shortName":"Delay",
                     "designation":"",
                     "ranges":{
                        "maximum":0.20000000298023224,
                        "minimum":0,
                        "default":0.019999999552965164
                     },
                     "name":"Delay",
                     "scalePoints":[

                     ],
                     "symbol":"delay",
                     "index":1
                  },
                  {
                     "units":{

                     },
                     "rangeSteps":null,
                     "properties":[

                     ],
                     "shortName":"Depth",
                     "designation":"",
                     "ranges":{
                        "maximum":1,
                        "minimum":0,
                        "default":0.019999999552965164
                     },
                     "name":"Depth",
                     "scalePoints":[

                     ],
                     "symbol":"depth",
                     "index":2
                  },
                  {
                     "units":{
                        "label":"hertz",
                        "render":"%f Hz",
                        "symbol":"Hz"
                     },
                     "rangeSteps":null,
                     "properties":[

                     ],
                     "shortName":"Freq",
                     "designation":"",
                     "ranges":{
                        "maximum":10,
                        "minimum":0.10000000149011612,
                        "default":3
                     },
                     "name":"Freq",
                     "scalePoints":[

                     ],
                     "symbol":"freq",
                     "index":3
                  }
               ],
               "output":[

               ]
            },
            "midi":{
               "input":[

               ],
               "output":[

               ]
            }
         },
         "microVersion":3,
         "brand":"Guitarix",
         "id":"56a8bae52f1d0e03d12aa483",
         "author":{
            "name":"Guitarix team",
            "homepage":"",
            "email":"brummer@web.de"
         },
         "bundles":[

         ],
         "license":"http://opensource.org/licenses/isc",
         "bundle_multi_plugins":false,
         "label":"GxChorus-Stereo",
         "bundle_name":"gx_chorus.lv2",
         "version":"3.28",
         "href":"http://api.dev.moddevices.com/v2/lv2/plugins/56a8bae52f1d0e03d12aa483/",
         "release_number":2,
         "screenshot_available":true,
         "bundle_href":"http://api.dev.moddevices.com/v2/lv2/bundles/56a8bae42f1d0e03d12aa478/",
         "bundle_id":"56a8bae42f1d0e03d12aa478",
         "binary":"gx_chorus.so",
         "category":[
            "Modulator",
            "Chorus"
         ],
         "minorVersion":28,
         "gui":{
            "color":"petrol",
            "panel":"5-knobs",
            "screenshot":"modgui/screenshot-gxchorus-stereo.png",
            "resourcesDirectory":"modgui",
            "ports":[
               {
                  "name":"Depth",
                  "symbol":"depth",
                  "index":0
               },
               {
                  "name":"Rate",
                  "symbol":"freq",
                  "index":1
               },
               {
                  "name":"Delay",
                  "symbol":"delay",
                  "index":2
               },
               {
                  "name":"Level",
                  "symbol":"level",
                  "index":3
               }
            ],
            "brand":"Guitarix",
            "stylesheet":"modgui/stylesheet-gxchorus-stereo.css",
            "knob":"bronze",
            "label":"Chorus Stereo",
            "iconTemplate":"modgui/icon-gxchorus-stereo.html",
            "thumbnail":"modgui/thumbnail-gxchorus-stereo.png",
            "model":"boxy"
         },
         "thumbnail_available":true,
         "uri":"http://guitarix.sourceforge.net/plugins/gx_chorus_stereo#_chorus_stereo",
         "name":"GxChorus-Stereo",
         "screenshot_href":"http://api.dev.moddevices.com/v2/lv2/plugins/56a8bae52f1d0e03d12aa483/screenshot/",
         "thumbnail_href":"http://api.dev.moddevices.com/v2/lv2/plugins/56a8bae52f1d0e03d12aa483/thumbnail/"
      }
   }
}

Notification on_effect_status_toggled

  • Parameters:

    • type: string - "EFFECT-TOGGLE"
    • bank: number - Bank index
    • pedalboard: number - Pedalboard index
    • effect: number - Index of effect whose status was toggled

  • Example:

    {
    "type": "EFFECT-TOGGLE",
    "bank": 2,
    "pedalboard": 1,
    "effect": 3
}

Notification on_param_value_changed

  • Parameters:

    • type: string - "PARAM"
    • bank: number - Bank index
    • pedalboard: number - Pedalboard index
    • effect: number - Effect index
    • param: number - Param index
    • value: number - New param value

  • Example:

    {
  "type":"PARAM",
  "bank":2,
  "pedalboard":0,
  "effect":2,
  "param":1,
  "value":28.9453125
}

Notification on_connection_updated

  • Parameters:

    • type: string - "CONNECTION"
    • updateType: enum[string] - (CREATED | UPDATED | DELETED)
    • bank: number - Bank index
    • pedalboard: number - Pedalboard index
    • value: object - Connection between an output of an effect and an input of another effect

  • Example 1: Connection between Lv2Effects

    {
   "type":"CONNECTION",
   "updateType":"CREATED",
   "bank":2,
   "pedalboard":0,
   "value":{
      "input":{
         "effect":3,
         "symbol":"in1",
         "index":7
      },
      "output":{
         "effect":2,
         "symbol":"out_l",
         "index":2
      }
   }
}

  • Example 2: Connection between SystemEffect and Lv2Effect

    {
   "type":"CONNECTION",
   "updateType":"CREATED",
   "bank":2,
   "pedalboard":0,
   "value":{
      "input":{
         "effect":2,
         "symbol":"in_l",
         "index":0
      },
      "output":{
         "symbol":"capture_1",
         "index":0
      }
   }
}

Generated by aglio on 28 May 2017