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:
editor.connect(token)
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.
editor.close()
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.
editor.closed()
The closed
function returns a boolean value indicating if the editor
was closed.
editor.onclose(cb)
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.
editor.onready(cb)
A callback passed to the onready
function will be called once the editor is connected and ready to accept commands.
editor.onvisible(cb)
, callscb(first, last)
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.
editor.set_markers(markers, samples = false, push_state = true)
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.
editor.send_command(command_name)
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.
editor.ondirty(cb)
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.
editor.start_recording()
Calling start_recording()
will start recording.
editor.stop_recording()
Calling stop_recording()
will stop recording.
editor.set_visible(beg, end)
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.
- 2015-03-12 First version of the API and documentation.
- 2015-07-18 Added the
recording_format
andallow_vst_effects
edit options. - 2016-01-18 Added the
sample_rate
andmarkers
fields to the documents. - 2016-01-25 Added the
begin
andend
fields to the outputs, and added the possibility to show the editor in an iframe. - 2016-05-16 Added the possibility to import/export files from/to AWS S3.
- 2016-06-10 Added a number of
show_...
options to the edit object to customize what parts of the editor should be visible. - 2016-06-23 Added the
ttl
attribute to the documents to allow them to expire and be deleted automatically. - 2016-11-15 Added the
colors
attribute to the edit object to use custom colors on the editor. - 2016-12-15 Added the
auto_play
attribute to the edit object to start playing audio when the editor is loaded. - 2016-12-20 Added the
if_modified
attribute to the output object to export only modified files, and theondirty
function on the javascript SDK to be notified when the file is being edited. - 2017-01-12 Added the
toolbar_below
attribute to the edit object to specify that the toolbar should be placed below the main waveform view. - 2018-11-08 Added support for exporting AAC files.
- 2020-05-08 Added the
exported_filename
parameter to the output object to specify the name of the file exported by the API. - 2020-07-03
- Added the
title
,edit_observer
andselection_observer
to the JavaScript configuration options. - Added the
start_recording()
,stop_recording()
, andset_visible()
member functions to theeditor
object in the JavaScript SDK. - Added the
note
parameter to the edit object to store arbitrary metadata.
- Added the
- 2020-07-09 Added the
post_note
parameter to the output object to ask TwistedWave to post thenote
member along with the processed file. - 2020-07-15 Added the
send_command()
member function to theeditor
object in the JavaScript SDK, and theenabled_commands_observer
to the editor configuration options. These two can be used to build a custom toolbar or menu bar. - 2020-07-16 Added the
show_toolbar
options to the edit object to optionally hide the toolbar. Added thedoc_state_observer
to the JavaScript configuration options. - 2020-07-30 Added the
onready()
,onvisible()
, andset_markers()
member functions to theeditor
object in the JavaScript SDK. - 2020-09-23 The JavaScript SDK accidentally depended on jQuery.