NAV

Introduction

Welcome to the TwistedWave Online API!

With this API, you can open an audio editor window from your own web site, and have your users edit audio files.

Authentication

Example Request

$ curl https://twistedwave.com/online/api/jobs \
    -u XHCbGg_uN6PcepxCfDjd:

# curl uses the -u flag to pass basic auth credentials (adding a colon
# after your API key will prevent it from asking you for a password).

Make sure to replace XHCbGg_uN6PcepxCfDjd with your API key.

You authenticate to the TwistedWave API by providing one of your API keys in the request. You can manage your API keys from your account. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!

Authentication to the API can occur either via HTTP Basic Auth, or via Bearer Token Authentication.

For the basic authentication, provide your API key as the basic auth username. You do not need to provide a password. The HTTP header would look like:

Authorization: Basic WEhDYkdnX3VONlBjZXB4Q2ZEamQ6

With the Bearer Token Authentication, the API key should be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer XHCbGg_uN6PcepxCfDjd

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

Jobs

In order to start editing a file, you should create a job. A job object tells TwistedWave where to get the file that should be edited from, how it should be edited, what file format should be used to save the result, and where to send the edited file.

The job object

Example job object

{
  "id": "job_3c6837c1",
  "state": "completed",
  "note": "your metadata",
  "document": {
    "id": "doc_6e4799cdb",
    "title": "zozo",
    "channels": 1,
    "duration": 2.56748,
    "sample_rate": 44100.0,
    "created_at": "2015-03-06T01:25:09.067Z"
  },
  "edit": {
    "token": "doc_6e4799cdb:msMDGwc4SRL8PQ8qOAuc",
    "max_duration": 60,
    "connected_at": "2015-03-06T01:25:10.107Z",
    "completed_at": "2015-03-06T01:25:21.379Z"
  },
  "output": {
    "state": "completed",
    "format": "wav",
    "url": "http://172.16.53.1:3000/main/upload",
    "file_size": 339722,
    "bit_depth": 24
  },
  "delete_document": false
}
Attributes Description
id read only The id of the job object.
state read only The current state of the job.
error read only This attribute is present when the job state is failed, and is a message indicating what went wrong.
document read only The document this job works on.
edit optional This is an edit object. It indicates that the document should be edited as part of this job. The token inside the edit attribute is what should be given to the javascript SDK to connect the editor window to this job.
output optional This is an output object. It represents the output of this job, and indicates what file format should be used, and where to send the file.
note optional This is a text field you can use to store arbitrary information.

The state of the job object can be one of:

State Description
pending The job is waiting for previous jobs on the same document to finish before it can start working.
importing The audio file is being imported from the URL specified for the document.
waiting The job is waiting for a connection from the audio editor.
editing The document is being edited.
exporting The editing window was closed, and the audio file is being exported.
completed The job was completed.
failed The job has failed. The failure details are stored in the error attribute.
cancelled The job was cancelled.

Create a new job

Example Request

{
  "document": {
    "url": "https://twistedwave.com/twr.wav",
    "title": "zozo",
    "ttl": 3600
  },
  "edit": {
    "max_duration": 60
  },
  "output": {
    "url": "http://172.16.53.1:3000/main/upload",
    "format": "wav",
    "bit_depth": 24
  },
  "note": "your metadata",
  "delete_document": false,
  "cancel_other": true
}

Example Response

{
  "id": "job_3b4d892b",
  "state": "importing",
  "document": {
    "id": "doc_6e2980285",
    "title": "zozo",
    "ttl": 3600,
    "channels": 2,
    "duration": 0,
    "sample_rate": 44100.0,
    "created_at": "2015-03-06T01:31:08.227Z"
  },
  "edit": {
    "token": "doc_6e2980285:hnpqhOBz4aj96YViQ4RS",
    "max_duration": 60
  },
  "output": {
    "state": "pending",
    "format": "wav",
    "url": "http://172.16.53.1:3000/main/upload",
    "bit_depth": 24
  },
  "note": "your metadata",
  "delete_document": false
}

This endpoint creates a new job.

HTTP Request

POST https://twistedwave.com/online/api/jobs

JSON Parameters

Parameter Description
document optional The document this job operates on. It can contain an id to specify an existing document, a url that indicates where to load the audio file from, a title that will be displayed in the editor window, and a ttl that will give an expiration time for the document. If the document is not specified, or does not contain an id or url, a new empty document will be created.
edit optional Specify an edit object if the document is to be edited.
output optional Specify an output object for the document to indicate what to do with the edited document.
note optional This is a text field you can use to store arbitrary information.
delete_document optional A boolean value that specifies whether the document should be deleted when the job was completed. The document is never deleted if the job is cancelled or fails.
cancel_other optional A boolean value that indicates if all other jobs on the specified document should be cancelled.

None of these parameters is required, but there should be at least either an edit or an output with an existing document. Otherwise, the job would have nothing to do.

If an output job is created, it will run once all the previous jobs are completed (successfully, cancelled or failed). When an edit, or edit and output job is created, it should be the only active job. If necessary, you can set cancel_other to true to have all the other jobs cancelled.

There should not be both an input and a document specified. If you want to import an audio file, specify only an input, and a new document will be created.

If you specify neither an input nor a document, a new, empty document will be created. If you create an empty document without an edit, that will result in an error.

The delete_document parameter defaults to true if an output with a url is specified. If no output with url is specified, the document will not be deleted after it was edited.

You will be able to create a new job with an output in order to export the edited document.

If the document is not deleted after the job is completed, you can create a new job with an output to export the audio, and/or delete the document.

If you set delete_document to true, and don't specify an output with an url, that will result in an error, as that would loose the audio.

If there is an edit as part of this job, you should give the token value returned as part of the edit object to the javascript SDK in order to connect the audio editor window to this job.

List all jobs

$ curl "https://twistedwave.com/online/api/jobs?document=1764" \
    -u XHCbGg_uN6PcepxCfDjd:

The above command returns JSON structured like this:

{
  "has_more": false,
  "data": [
    {
      "id": "job_3a4e37b1",
      "state": "completed",
      "document": {
        "id": "doc_6e2980285",
        "title": "zozo",
        "channels": 1,
        "duration": 60,
        "sample_rate": 44100.0,
        "created_at": "2015-03-06T01:31:08.227Z"
      },
      "edit": {
        "token": "doc_6e2980285:B9hfZb6DCMczNfBoFmn5",
        "max_duration": 60,
        "connected_at": "2015-03-07T01:00:29.209Z",
        "completed_at": "2015-03-07T01:00:40.196Z"
      },
      "output": {
        "state": "completed",
        "format": "wav",
        "url": "http://172.16.53.1:3000/main/upload",
        "file_size": 5292044,
        "bit_depth": 24
      },
      "delete_document": false
    },
    {
      "id": "job_3b4d892b",
      "state": "completed",
      "document": {
        "id": "doc_6e2980285",
        "title": "zozo",
        "channels": 1,
        "duration": 60,
        "sample_rate": 44100.0,
        "created_at": "2015-03-06T01:31:08.227Z"
      },
      "edit": {
        "token": "doc_6e2980285:hnpqhOBz4aj96YViQ4RS",
        "max_duration": 60,
        "connected_at": "2015-03-06T01:31:08.947Z",
        "completed_at": "2015-03-06T01:52:59.126Z"
      },
      "output": {
        "state": "completed",
        "format": "wav",
        "url": "http://172.16.53.1:3000/main/upload",
        "file_size": 339722,
        "bit_depth": 24
      },
      "delete_document": false
    }
  ]
}

Returns a list of jobs you've previously created. The jobs are returned in sorted order, with the most recent jobs appearing first.

Arguments Description
limit optional A limit on the number of objects to be returned. Limit can range between 1 and 100 items. The default value is 10.
starting_after optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
document optional Only return jobs for the document specified by this document ID.

HTTP Request

GET https://twistedwave.com/online/api/jobs

Returns

A dictionary with a data property that contains an array of up to limit jobs, starting after job starting_after. Each entry in the array is a separate job object. If no more jobs are available, the resulting array will be empty.

The has_more property is true if there are more jobs after the last one returned.

Get a specific job

$ curl "https://twistedwave.com/online/api/jobs/123" \
    -u XHCbGg_uN6PcepxCfDjd:

The above command returns JSON structured like this:

{
  "id": "job_3b4d892b",
  "state": "completed",
  "document": {
    "id": "doc_6e2980285",
    "title": "zozo",
    "channels": 1,
    "duration": 2.56748,
    "sample_rate": 44100.0,
    "created_at": "2015-03-06T01:31:08.227Z"
  },
  "edit": {
    "token": "doc_6e2980285:hnpqhOBz4aj96YViQ4RS",
    "max_duration": 60,
    "connected_at": "2015-03-06T01:31:08.947Z",
    "completed_at": "2015-03-06T01:52:59.126Z"
  },
  "output": {
    "state": "completed",
    "format": "wav",
    "url": "http://172.16.53.1:3000/main/upload",
    "file_size": 339722,
    "bit_depth": 24
  },
  "delete_document": false
}

This endpoint retrieves a specific job.

HTTP Request

GET https://twistedwave.com/online/api/jobs/{job-id}

URL Parameters

Parameter Description
job-id The ID of the job to retrieve

Cancel a job

$ curl "https://twistedwave.com/online/api/jobs/123/cancel" \
    -X PUT -u XHCbGg_uN6PcepxCfDjd:

This endpoint will cancel a job. If a document is currently being edited, the editor will be disconnected.

The document will not be deleted, even if the delete_document option was explicitly specified in the job.

HTTP Request

PUT https://twistedwave.com/online/api/jobs/{job-id}/cancel

URL Parameters

Parameter Description
job-id The ID of the job to retrieve

Download the output from a job

$ curl "https://twistedwave.com/online/api/jobs/123/download" \
    -u XHCbGg_uN6PcepxCfDjd:

This endpoint will download the exported file generated by the job's output. If an output does not have an url parameter, instead of being sent, the generated file is stored alongside the document, and should be downloaded by performing a GET request on this endpoint.

HTTP Request

GET https://twistedwave.com/online/api/jobs/{job-id}/download

URL Parameters

Parameter Description
job-id The ID of the job to retrieve

Edits

An Edit object is a member of a job, and specifies that an audio editor should be displayed to the user in order to edit the job's document.

There is no API endpoint to manipulate edit objects directly. They are always created and returned as a member of a job.

The edit object

{
  "token": "doc_6e2980285:hnpqhOBz4aj96YViQ4RS",
  "max_duration": 60,
  "connected_at": "2015-03-06T01:31:08.947Z",
  "completed_at": "2015-03-06T01:52:59.126Z"
}
Attribute Description
token read only This is the token that should be passed to the javascript SDK in order to connect the audio editor window to the editing job.
max_duration required This specifies the maximum length of the document edited by the user. TwistedWave will prevent the user from making documents longer than the specified number of seconds. A value of 0 means no limit on the document length. The value is automatically clamped to 5 seconds when the application is in test mode.
recording_format optional Can be one of raw, mp3_64, mp3_128 or mp3_320. When this attribute is specified, the recording options menu is not present, and the format used when recording is the one specified by that option.
allow_vst_effects optional Indicates whether the VST effects menu should be available. The default value is true.
allow_recording optional. Indicates if recording is allowed. The default value is true.
auto_play optional. Indicates that the editor should start playing audio as soon as it is loaded. The default value is false.
show_menu optional. Indicates if the menu bar should be visible. The default value is true.
show_title optional. Indicates if the title bar should be visible. The default value is true.
show_status_bar optional. Indicates if the status bar should be visible. The default value is true.
show_overview optional. Indicates if the overview should be visible. The default value is true.
show_overview_ruler optional. Indicates if the ruler above the overview should be visible. The ruler can only be shown if show_overview is also true. The default value is true.
show_main_ruler optional. Indicates if the ruler above the main waveform view should be visible. The default value is true.
show_markers optional. Indicates if the markers should be visible. If the markers ruler is not shown, the markers will still be displayed in the main waveform. The default value is true.
show_markers_ruler optional. Indicates if the markers ruler above the main waveform view should be visible. It can only be shown if show_markers is also true. The default value is true.
show_level_meter optional. Indicates if the level meter should be visible. The default value is true.
show_toolbar optional. Indicates if the toolbar should be visible. The default value is true.
toolbar_below optional. Indicates that the toolbar should be placed below the main waveform view. The default value is false.
colors optional This attribute can contain a hash providing custom colors for the editor. The keys of this hash are described below.
connected_at read only When present, indicates that the audio editor was successfully connected to the editing job, and when.
completed_at read only When present, indicates when the editing window was closed.

Custom Colors

It is possible to specify custom colors to be used by the editor by passing a colors hash as an attribute to the edit object. The keys of this hash are described below.

Some of the keys work by pair, with a xxx_top and xxx_bottom key. That means that the colors specify a gradient, and both keys are used to determine the color at the top and the color at the bottom of the object being painted.

Key Description
background_top background_bottom Background color for the waveform views.
selection_top selection_bottom Background color for a selection in the waveform view.
markers_top markers_bottom Background color of the markers view.
ruler_top ruler_bottom Background color of the rulers.
font_color Color used for the fonts in the satus view, rulers and toolbar.
cursor Cursor color.
markers Color of the markers.
marker_width This is a number specifying the width of the markers.
wave Color of the wave.
wave_selected Color of the wave when it is selected.
channel_separator Color of the channel separators.
center_line Color of the center line, in the center of each channel.
overview_window Color of the window showing the visible area in the overview.
toolbar_color Background color of the toolbar.
status_bar_color Background color of the status bar.

Outputs

An Output object is a member of a job, and specifies what file format to use, and where to send the the exported file.

Just as for the edit object, there is no API endpoint to manipulate output objects directly. They are always created and returned as a member of a job.

The output object

{
  "state": "completed",
  "format": "wav",
  "sample_rate": 44100,
  "url": "http://172.16.53.1:3000/main/upload",
  "file_size": 339722,
  "bit_depth": 24
}
Attribute Description
state read only Indicates the current state of the output. The different values are specified below.
url optional Indicates the URL where the exported file should be sent to. When the url is not specified, the generated file is not sent, but stored along with the document, and should be downloaded. See downloading the output from a job.
exported_filename optional If an URL is provided, this provides the name of the exported file that will be posted to the URL. The default is export.mp3, or with a different extension, depending on the file format selected.
post_note optional When this boolean value is true, the note member of the job object will be posted along with the file to the specified URL.
format required Specifies the file format to use when exporting the document.
sample_rate optional Tells TwistedWave to resample the audio at the given frequency before exporting it. This resampling is temporary and will not persist in the document. If another edit or output job is created on the same document, they will see the original sample rate.
begin optional This is a time in seconds that indicates the beginning of the region that will be exported, if you don't want to export the whole file.
end optional This is a time in seconds that indicates the end of the region that will be exported, if you don't want to export the whole file.
begin_sample optional This is the same as the begin attribute, except that it is an integer number of samples instead of a time in seconds. If the sample_rate parameter is specified, this value is relative to the new sample rate, and not the original sample rate in the file.
end_sample optional This is the same as the end attribute, except that it is an integer number of samples instead of a time in seconds. If the sample_rate parameter is specified, this value is relative to the new sample rate, and not the original sample rate in the file.
public optional When the destination url is an s3 object, the created object is private by default. In order to make it publicly readable, set a public parameter to true. You should not give a public parameter when not sending to s3.
if_modified optional A boolean value that indicates that this output should be performed only if the file was modified since last time it was exported.

Depending on the format selected, extra format options can also be specified, as discussed below.

Partial file export

If you don't want to export the whole file, you can specify the beginning and the end of the region you want to export with the begin and end parameters. Note that you can specify only one of these if you only want to export or skip the first n seconds.

The begin_sample and end_sample parameters indicate the samples that should be exported. The samples are numbered starting at 0. The sample begin_sample is the first sample to be included in the output, and the sample just before end_sample is the last one to be included in the output. When both parameters are specified the number of samples in the output is therefore end_sample - begin_sample.

S3 upload

It is possible to have the exported file saved in an S3 object by specifying a url parameter in the form s3://your-bucket-name/path/to/file.wav.

Files saved to S3 are private by default, but it is possible to make them publicly readable by giving a public parameter with a value of true.

Output object state

The state of the output object can be one of:

State Description
pending The output is waiting for the editor or previous jobs on the same document to finish before it can start exporting the document.
encoding The document is being encoded with the specified file format.
sending The document was encoded, and is being sent to the specified url.
completed The output was completed.
skipped The output was not performed, because the if_modified argument was true and the document was not modified since last time it was exported.
failed This output is part of a failed job.
cancelled This output's job was cancelled.

File formats

All the file formats can have additional options to specify the encoding details. All these options are optional and have default values.

WAV

This is the WAVE audio file format, and is selected with a format attribute equal to wav.

Option Description
codec Can be one of none, u_law, a_law, ima4 or ms_adpcm. The default value is none.
bit_depth Can be one of 8, 16, 24 or 32. The default value is 16. This option can only be specified when the codec is none.

MP3

This is the MP3 file format, and is selected with a format attribute equal to mp3.

Option Description
vbr This is a boolean value (true or false) that specifies whether to use a variable bitrate encoding. The default value is false.
joint_stereo This option is a boolean value (true or false), and indicate that when encoding a two channel file, it should be treated as a stereo file, and not two independent channels. It provides a better audio quality with stereo files. This option can be provided, but has no effect when encoding mono files. The default value is true.
vbr_quality This is a value between 0 and 9 that specifies the quality of vbr encoded files, and can only be specified if the vbr option is true. 0 produces the best quality, and 9 the smallest files. The default is 2.
bit_rate This option specifies the bit rate in kbps, and is only accepted when vbr is false. It can be one of 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256 or 320. The default value is 128 kbps.
quality This is a number between 0 and 9 that specifies the encoding quality. 0 being the best quality, and 9 the fastest option. The default is 2.

FLAC

This is the FLAC (Free Lossless Audio Codec) file format, and is selected with a format attribute equal to flac.

Option Description
compression_level This is a number between 0 and 8 that indicates the compression level. 0 is the fastest, and 8 the highest compression. The default value is 5.
bit_depth Can be one of 16, 20 or 24. The default value is 16.

ogg

Option Description
vbr This is a boolean value (true or false) that specifies whether to use a variable bitrate encoding. The default value is false.
bit_rate This option specifies the bit rate in kbps, and is only accepted when vbr is false. It can be one of 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256 or 320. The default value is 128 kbps.
vbr_quality This is a value between 0 and 10 that specifies the quality of vbr encoded files, and can only be specified if the vbr option is true. 0 produces the smallest files, and 10 the best quality. The default is 7.

wv

This is the WavPack audio file format, and is selected with a format attribute equal to wv.

Option Description
compression_level This is a number between 0 and 3 that indicates the compression level. 0 is the default, 1 is high compression, 2 is very high compression and 3 is fast.
bit_depth Can be one of 8, 16, 20, 24 or 32. The default value is 16.

w64

This is the Wave64 audio file format, and is selected with a format attribute equal to w64.

Option Description
codec Can be one of none, u_law, a_law, ima4 or ms_adpcm. The default value is none.
bit_depth Can be one of 8, 16, 24 or 32. The default value is 16. This option can only be specified when the codec is none.

mp2

This is the MP2 file format, and is selected with a format attribute equal to mp2.

Option Description
bit_rate This option specifies the bit rate in kbps, and can be one of 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256 or 320. The default value is 128 kbps.

aiff

This is the AIFF (Audio Interchange File Format) file format, and is selected with a format attribute equal to aiff.

Option Description
bit_depth Can be one of 8, 16, 24 or 32. The default value is 16.

aifc

This is the AIFF-C (Audio Interchange File Format Compressed) file format, and is selected with a format attribute equal to aifc.

Option Description
codec Can be one of none, u_law, a_law, ima4 or ms_adpcm. The default value is none.
bit_depth Can be one of 8, 16, 24 or 32. The default value is 16. This option can only be specified when the codec is none.

au

This is the AU file format, and is selected with a format attribute equal to au.

Option Description
codec Can be one of none or u_law. The default value is none.
bit_depth Can be one of 8, 16, 24 or 32. The default value is 16. This option can only be specified when the codec is none.

wma

This is the WMA (Windows Media Audio) file format, and is selected with a format attribute equal to wma.

Option Description
bit_rate This option specifies the bit rate in kbps, and can be one of 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256 or 320. The default value is 128 kbps.

caf

This is the CAF (Core Audio Format) file format, and is selected with a format attribute equal to caf.

Option Description
codec Can be one of none, u_law, a_law. The default value is none.
bit_depth Can be one of 8, 16, 24 or 32. The default value is 16. This option can only be specified when the codec is none.

aac

This is the AAC (Advanced Audio Coding) file format, and is selected with a format attribute equal to aac.

Option Description
bit_rate This option specifies the bit rate in kbps, and can be one of 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256 or 320. The default value is 128 kbps.

Documents

A document represents an audio file that can be edited with the TwistedWave Online Audio Editor.

A document is created implicitly by any job that does not specify an already existing document. When a job is completed, the document can be deleted, or preserved and edited or output again. When multiple edits are done on the same document, the whole undo history is preserved.

When an output is created without an url parameter, the generated file is stored along with the document. If the document is deleted, any output associated with it cannot be downloaded anymore. Any attempt will return a 404 error.

The document object

{
  "id": "doc_6e1fdc020",
  "title": "zozo",
  "ttl": 3600,
  "channels": 1,
  "duration": 12.34,
  "sample_rate": 44100.0,
  "markers": [
      [28458, "Marker 1"],
      [62335, "Marker 2"]
    ],
  "created_at": "2015-03-06T01:31:08.227Z",
  "deleted_at": "2015-03-07T05:13:28.123Z"
}
Attribute Description
id The id of the document object.
title The title of the document, as it will be displayed in the editor. This field is not present if the document is untitled.
ttl The "time to live" in seconds. The document will automatically be deleted if it was last edited ttl seconds ago. Documents don't expire if no ttl is specified.
channels Channel count.
duration The duration in seconds.
sample_rate The sample rate of the document.
markers When it is present, this attribute lists the markers present in the audio file. Each markers is represented by a pair. The first element is the position of the marker in samples from the beginning of the file. The second element is the marker name.
created_at The creation date of the document.
deleted_at This attribute is present if the document was deleted, and indicates the deletion date.

Note that the title, channels, duration, sample_rate and markers attributes are not available until the document was edited. Once the document editor was closed, these fields are filled and are returnend by the API.

Get a specific document

$ curl "https://twistedwave.com/online/api/documents/123" \
    -u XHCbGg_uN6PcepxCfDjd:

The above command returns JSON structured like this:

{
  "id": "doc_6e1fdc020",
  "title": "zozo",
  "channels": 1,
  "duration": 12.34,
  "sample_rate": 44100.0,
  "markers": [
      [28458, "Marker 1"],
      [62335, "Marker 2"]
    ],
  "created_at": "2015-03-06T01:31:08.227Z"
}

This endpoint retrieves a specific document.

HTTP Request

GET https://twistedwave.com/online/api/documents/{doc-id}

URL Parameters

Parameter Description
doc-id The ID of the document to retrieve

Delete a document

$ curl "https://twistedwave.com/online/api/documents/123" \
    -X DELETE -u XHCbGg_uN6PcepxCfDjd:

This endpoint deletes a document.

HTTP Request

DELETE https://twistedwave.com/online/api/documents/{doc-id}

URL Parameters

Parameter Description
doc-id The ID of the document to delete

List all documents

$ curl "https://twistedwave.com/online/api/documents?limit=2" \
    -u XHCbGg_uN6PcepxCfDjd:

The above command returns JSON structured like this:

{
  "has_more": true,
  "data": [
    {
      "id": "doc_6e2980285",
      "title": "zozo",
      "channels": 1,
      "duration": 60,
      "sample_rate": 44100.0,
      "created_at": "2015-03-06T01:31:08.227Z"
    },
    {
      "id": "doc_6e4799cdb",
      "title": "zozo",
      "channels": 1,
      "duration": 2.56748,
      "sample_rate": 44100.0,
      "created_at": "2015-03-06T01:25:09.067Z"
    }
  ]
}

Returns a list of documents you've previously created. The documents are returned in sorted order, with the most recent documents appearing first.

Arguments Description
limit optional A limit on the number of objects to be returned. Limit can range between 1 and 100 items. The default value is 10.
starting_after optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
include_deleted optional Indicates whether the deleted documents should be included in the list. The default value is false.

HTTP Request

GET https://twistedwave.com/online/api/documents

Returns

A dictionary with a data property that contains an array of up to limit documents, starting after document starting_after. Each entry in the array is a separate document object. If no more documents are available, the resulting array will be empty.

The has_more property is true if there are more documents after the last one returned.

Notifications

Notifications are sent to the endpoint you have configured in your developer account. They are sent when changes happen to your job objects, such as when a document was edited, or the job was completed.

A notification delivery is considered successful if the HTTP request gets a 2xx response code. If it fails, the notification is retried up to 20 times at a decreasing frequency for up to three days.

The notification object

{
  "type": "job.completed",
  "job": {
    "id": "job_3c6837c1",
    "state": "completed",
    "document": {
      "id": "doc_6e4799cdb",
      "title": "zozo",
      "channels": 1,
      "duration": 2.56748,
      "sample_rate": 44100.0,
      "markers": [
          [28458, "Marker 1"],
          [62335, "Marker 2"]
        ],
      "created_at": "2015-03-06T01:25:09.067Z"
    },
    "edit": {
      "token": "doc_6e4799cdb:msMDGwc4SRL8PQ8qOAuc",
      "max_duration": 60,
      "connected_at": "2015-03-06T01:25:10.107Z",
      "completed_at": "2015-03-06T01:25:21.379Z"
    },
    "output": {
      "state": "completed",
      "format": "wav",
      "url": "http://172.16.53.1:3000/main/upload",
      "file_size": 339722,
      "bit_depth": 24
    },
    "delete_document": false
  }
}
Attributes Description
type This is the type of notification.
job This is the job that triggered the notification.
document The document that triggered the notification, when the notification type is document.expired

A notification object has always one of the job or document attribute, depending on whether the notification was triggered by a job or a document. The only notification that can be triggered by a document is currently the document.expired notification.

The different notification types are:

Type Description
edit.completed This notification is sent when the edit window was closed.
job.completed This notification is sent when the job was completed.
job.failed This notification is sent when the job has failed.
document.expired This notification is sent when a document has expired. Documents expire when they have a ttl attribute.

S3 Import and Export

It is possible to edit audio files from an s3 object, and export the edited audio to another s3 object.

In order to do that, you should specify a parameter in the form s3://your-bucket-name/path/to/file.wav either for the input or output url of the job.

Files saved to S3 are private by default, but it is possible to make them publicly readable by giving a public parameter to the output of a job with a value of true.

For TwistedWave to download files, they either need to be accessible by everyone or a bucket policy needs to be added to your bucket that will grant TwistedWave access.

In order to allow TwistedWave to import/export files to your s3 bucket, you should create a bucket policy that grants the s3:GetObject and/or s3:PutObject actions to TwistedWave's AWS account identified either by this ARN: arn:aws:iam::234222569268:root or this canonical user ID: 47e154fe2052de2f913ba415fabac7f0961b81deff0db146c01607d6fc1362cc.

Javascript SDK

The javascript SDK is available by including the following javascript file:

https://twistedwave.com/online/sdk.js

When this file is included, a global object TW is created. This object contains two functions that can be used to show the audio editor, newDocumentWindow and newDocumentIframe.

You can call the newDocumentWindow function to open a new pop-up window with the TwistedWave Online editor:

editor = TW.newDocumentWindow([options]);

Because this function opens a pop-up window, it is recommended to call it from a click handler in order to avoid having the pop-up blocked by the web browser.

If you don't want to open the editor in a new window, you can use the function newDocumentIframe to open it in an iframe:

editor = TW.newDocumentIframe(document.getElementById("editor")[, options]);

This function takes one argument, the DOM element inside which the editor should be placed. It should be an empty div of size at least 730 x 300.

The editor that shows up is empty and shows "Loading...". It will only display the editor once it is connected to a job you have created.

Configuration options

Both the newDocumentWindow and newDocumentIframe functions take an optional options parameter that can contain a number of fields as described in this table:

Name Description
title When using the pop-up editor with the newDocumentWindow call, this will specify the title to use for the editor window.
edit_observer This is a callback function that will be called each time an edit is performed (cut, paste, apply an effect...).
selection_observer This is a callback function that will be called each time the selection changes.
enabled_commands_observer This is a callback function that will be called each time the list of enabled commands changes. This should be used to enable / disable user interface elements used to send with the send_command described below.
doc_state_observer This is a callback function that is called when the document state changes. See below for details on the contents of the document state.

Edit observer

Example object passed to the edit observer

{
  "doc_state": {
    "sample_count": 190491,
    "sample_rate": 44100
  },
  "last_edit": {
    "cursor_after": 115306,
    "cursor_before": 115306,
    "id": "cut",
    "sel_after": null,
    "sel_before": [
      115306,
      145315
    ]
  }
}

When an edit observer is registered, the callback is called each time an operation that modifies the document is performed. The callback is passed a single argument, an object with two properties.

The last_edit property provides some information on the last edit that has occurred. The id property is a string that identifies the kind of operation that was performed, such as "cut", "graphic-eq"...

Except in the case of the "undo" and "redo" operations, the last_edit also contains some information such as the position of the cursor and selection before, and after the edit was completed.

Additionally, a doc_state property provides information on the total sample count and the sample rate of the document. The latter can be useful to convert the selection position to a time in seconds.

Selection observer

Example object passed to the selection observer

{
  "doc_state": {
    "sample_count": 220500,
    "sample_rate": 44100
  },
  "selection": [
    115306,
    145315
  ]
}

When a selection observer is registered, the callback is called each time the selection is updated. The callback is passed a single argument, an object with two properties.

The selection property is either null, if nothing is selected, or an array of two elements, the start and end position of the selection.

Additionally, a doc_state property provides information on the total sample count and the sample rate of the document. The latter can be useful to convert the selection position to a time in seconds.

Document state observer

Example object passed to the document state observer

{
  "processing_effect_progress": 1,
  "redo_name": null,
  "undo_name": "Normalize",
  "channel_count": 2,
  "sample_count": 220500,
  "is_processing": false,
  "doc_name": "The Title",
  "processing_effect_name": "Ready",
  "bit_depth": 16,
  "sample_rate": 44100
}

When a document state observer is registered, the callback is called each time the state changes with an object that contains some information document being edited.

Name Description
doc_name Name of the document.
bit_depth Bit depth.
channel_count Channel count.
sample_count Sample count.
sample_rate Sample rate.
is_processing Boolean that indicates if an effect is currently being applied
processing_effect_name When an effect is being applied, this is the name of the effect. It says "Ready" when not processing.
processing_effect_progress A number between 0 and 1 that indicates the progress of the current task.
undo_name This is the name of the effect that will be undone, if any, when the undo button is pressed.
redo_name This is the name of the effect that will be redone, if any, when the redo button is pressed.

Editor member functions

The editor object returned by either newDocumentWindow() or newDocumentIframe() has four member functions:

In order to connect the editor to the job, you should pass it the edit token. This token is a member of the edit attribute of the job object that you have created. Calling the editor's connect function will connect the audio editor to the job:

editor.connect(job.edit.token);

Once connected, the editor will show a progress bar if the audio file has not finished downloading from the URL that was specified, and then show the file waveform.

The close function will close the editor window or remove its iframe, depending on which one is being used. TwistedWave will then send the document to the job's output if one was specified.

The closed function returns a boolean value indicating if the editor was closed.

You can pass a callback to the onclose function to be notified when the editor window is closed. The editor can be closed either by a call to the editor.close() function, or by the user closing the window. In the case of an iframe, the user cannot manually close the editor. You should provide a button that calls the close function to allow the user to close the editor.

Only a single onclose handler can be installed per editor object.

A callback passed to the onready function will be called once the editor is connected and ready to accept commands.

A callback passed to the onvisible function will be called when the visible part of the audio file changes, when zooming or scrolling for instance.

The callback is passed two parameters, named first and last. These parameters are the time in seconds of the first and last visible samples in the audio file.

You can pass a list of markers to add to the loaded audio file by calling set_markers.

The markers parameter is an array of markers. Each marker is itself an array of two elements. The first element is the marker position, in seconds, or in samples if the optional samples parameter is set to true. The second element is the marker name.

After a call to set_markers(), a new state is pushed to the undo stack, and the user can press undo to cancel that action.

If push_state is set to false, then TwistedWave won't push a new state. This can be useful when setting markers to a file just after it has been loaded. The user won't be able to undo the setting of markers.

It is possible to simulate user actions by using the send_command function. command_name is a string than indicates the command to be sent to the editor, and can be one of:

add-marker, amplify, analyze, center-on-cursor, clear-markers, close, convert-sampling-rate, convert-to-mono, convert-to-stereo, copy, crop, cut, delete, delete-crossfade, denoise, dump-db, export-download, export-googledrive, export-soundcloud, fade-in, fade-out, fast-forward, graphic-eq, insert-silence, invert-polarity, learn-noise, loop, loop-crossfade, mark-in, mark-out, metadata, move-cursor-back, move-to-end, move-to-start, normalize, paste, paste-over, pitch-speed, play, record, record-mp3-128, record-mp3-320, record-mp3-64, record-raw, redo, remove-dc, reverse, rewind, select-all, select-audio-input, select-none, select-to-end, select-to-start, silence, trim-silences, undo, view-whole-sound, zoom-in, zoom-out, zoom-to-selection

The command names should give enough clue at what they do. These can be used to build a toolbar or menu with your own design. When a button is pressed in your toolbar, you would send the corresponding command to TwistedWave with the send_command function.

Note that some commands can be disabled in some cases. The copy command is disabled if nothing is selected, for instance. You should use the enabled_commands_observer described above in order to be notified when commands become enabled or disabled, and reflect this in your UI.

You can pass a callback to the ondirty function to be notified when the editor has unsaved changes. The callback is called once the editor is loaded, and once every time the dirty status changes.

The callback is called with two boolean arguments.

The first argument, can_undo, is true if any edit was done to the edited file since it was first loaded. Even if the file was not edited in the current editing session, the can_undo parameter can be true if the file was previously edited.

The second argument, dirty, is true if the file was edited since its last export, or since it was loaded if the file has not been exported yet.

Only a single ondirty handler can be installed per editor object.

Calling start_recording() will start recording.

Calling stop_recording() will stop recording.

You can call the set_visible function to jump to a specific position in the waveform. The beg argument is the first visible sample, and end is one after the last visible sample. If you want to zoom out and show the whole waveform, you should pass 0 and the sample count of the file.

The visible area is automatically adjusted to remain inside the file if a sample less than 0, or greater than the number of samples in the whole file is passed.

Changelog

This section lists the main changes to the API or its documentation.