Align Magix API
Our flagship alignment service Align Magix ® is offered in the form of a fast and simple REST API.
USAGE FAQ
Q: How accurate is the generated alignment?
A: There could be significant differences in the accuracy of the alignment from a song to song depending on many factors. Among them the most important are the background music instruments, the speed of singing and the genre. Also have a look at our demos at demo.voicemagix.com
Q: How fast is the Align Magix ® API?
A: The processing time it takes to align a 4-minute recording on the currently deployed API infrastructure is on average 30 seconds for an a cappella recording and 50 seconds for a multi-instrumental mix. Upon request the processing speeds could be increased, reflecting the price. For more details, please contact [email protected]
Q: How many recordings can be aligned simultaneously by the Align Magix ® API?
A: The API is at the first place not intended for heavy load (like for example, multiple real-time audio streams). With that in mind, the API can process a limited amount of recordings simultaneously. Depending on the use case this can vary between 2 and 4. The parameters that matter for the time it takes to process one alignment are lyrics_format and accompaniment. For example, standard lyrics_format (= 1) and multi-instrumental accompaniment (=2) means more processing power, so our recommendation is not to run more than 2 alignments at a time.
Q: How much does it cost to use the Align Magix ® API?
A: We license the API with a prepayment for different packages of minutes of processed audio (a minimum of 5K minutes). The prices start at 0.15 € per minute of processed audio depending on the package you select. The package of minutes is valid for a subscription period (a minimum of 3 months). For more concrete prices, please contact [email protected]
Q: Can I evaluate the Align Magix ® API without having to pay?
A: Yes, It can be tested for evaluation purposes for a limited period (two weeks). You need first to contact [email protected] to request an evaluation license. Once we agree, we will create an account for you and then you can use the endpoint auth/token/ to generate a token, which can be used to authenticate you in subsequent calls to the API.
Q: After being authenticated I still keep getting "Invalid credentials. Please try again!” even though my credentials are correct?
A: Make sure that the content type is correct. The “multipart/form-data” is needed only if you are uploading a lyrics_file on the alignments/ endpoint. Otherwise use "application/json".
A: There could be significant differences in the accuracy of the alignment from a song to song depending on many factors. Among them the most important are the background music instruments, the speed of singing and the genre. Also have a look at our demos at demo.voicemagix.com
Q: How fast is the Align Magix ® API?
A: The processing time it takes to align a 4-minute recording on the currently deployed API infrastructure is on average 30 seconds for an a cappella recording and 50 seconds for a multi-instrumental mix. Upon request the processing speeds could be increased, reflecting the price. For more details, please contact [email protected]
Q: How many recordings can be aligned simultaneously by the Align Magix ® API?
A: The API is at the first place not intended for heavy load (like for example, multiple real-time audio streams). With that in mind, the API can process a limited amount of recordings simultaneously. Depending on the use case this can vary between 2 and 4. The parameters that matter for the time it takes to process one alignment are lyrics_format and accompaniment. For example, standard lyrics_format (= 1) and multi-instrumental accompaniment (=2) means more processing power, so our recommendation is not to run more than 2 alignments at a time.
Q: How much does it cost to use the Align Magix ® API?
A: We license the API with a prepayment for different packages of minutes of processed audio (a minimum of 5K minutes). The prices start at 0.15 € per minute of processed audio depending on the package you select. The package of minutes is valid for a subscription period (a minimum of 3 months). For more concrete prices, please contact [email protected]
Q: Can I evaluate the Align Magix ® API without having to pay?
A: Yes, It can be tested for evaluation purposes for a limited period (two weeks). You need first to contact [email protected] to request an evaluation license. Once we agree, we will create an account for you and then you can use the endpoint auth/token/ to generate a token, which can be used to authenticate you in subsequent calls to the API.
Q: After being authenticated I still keep getting "Invalid credentials. Please try again!” even though my credentials are correct?
A: Make sure that the content type is correct. The “multipart/form-data” is needed only if you are uploading a lyrics_file on the alignments/ endpoint. Otherwise use "application/json".
Endpoints Description
POST HTTP://API.VOICEMAGIX.COM/AUTH/TOKEN/
REQUEST BODY DATA (JSON) |
VALUE TYPE |
VALUE |
username |
Required. text |
- |
password |
Required. text |
- |
Generates an authentication token for given credentials. On success it returns the user information and the generated token together with a 200 OK HTTP status code in the response header. Using the given token one has to add to all following three methods a header key Authorization with value ‘Bearer <token>‘
NOTE: A token is generated only once for a given user. Therefore, make sure you write down your token! Upon approaching expiration, depending on the period of your agreement with us, a token could be extended for a given limited amount of time.
NOTE: A token is generated only once for a given user. Therefore, make sure you write down your token! Upon approaching expiration, depending on the period of your agreement with us, a token could be extended for a given limited amount of time.
An example request:
curl --request POST --url http://api-demo.voicemagix.com/auth/token/ --form username=testuser --form password=testpassword
POST HTTP://API.VOICEMAGIX.COM/AUTH/TOKEN/VERIFY/
REQUEST BODY DATA (JSON) |
VALUE TYPE |
VALUE |
token |
Required. string |
- |
Verifies if an authentication token is valid. The purpose of the endpoint is to help keep track of the lifetime of a token. On success it returns the token and the expiry date together with a 200 OK HTTP status code in the response header. If the token has expired, it returns a message 'Signature has expired' with a 400 header.
An example request:
curl --request POST --url http://api-demo.voicemagix.com/auth/token/verify/ --form token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo0LCJ1c2VybmFtZSI6InRlc3QyIiwiZXhwIjoxNTYyMzU1ODU0LCJlbWFpbCI6IiIsIm9yaWdfaWF0IjoxNTYxMDU5ODU0fQ.j2W5p9my7NlDHk9U_tIPLcOPuOX3aG7_6LbvAMgE3do
POST HTTP://API.VOICEMAGIX.COM/ALIGNMENTS/
REQUEST BODY DATA (JSON) |
VALUE TYPE |
VALUE |
lyrics_text |
Lyrics as text. Separate lyrics lines by \n character. |
Example: “line lyrics one\nline lyrics two” |
lyrics_file |
Lyrics text file as attachment where each lyrics line is on a new line. |
- |
lyrics_format |
integer |
[1,2] 1=plain, 2 = lrc. default = 1 |
recording_URL |
text |
- |
accompaniment |
Required. integer |
{1,2} 1=acapella, 2=multi-instrumental |
level |
integer |
{1,2}, 1=words, 2=lines. default= 1 |
title |
text. The title of the composition |
if not given will be blank in the alignment result |
end_times |
integer |
{1,2} 1=no, 2=yes. default= 1 |
composition_id |
hash |
- |
Creates an alignment request. On success, the response body contains an alignment_id and composition_id in JSON format and the HTTP status code in the response header is 201 Created. The alignment_id is used to identify future audio upload and result requests. The composition_id is used in future alignment requests for a recording with same lyrics, e.g. that is the same composition.
Lyrics could be given as either string or as a text file. If lyrics are given as a file, the post type should be ‘multipart/form-data’, otherwise ‘application/json’ is recommended. Meaningful lyrics lines are encouraged as they could help increase the alignment accuracy. One of lyrics_text, lyrics_file or composition_id has to be input. The lyrics_format is by default plain, which means only lyrics text. The lrc format stands for simple lrc - e.g. each lyrics line is prepended by a reference timestamp.
The audio file has to be passed as a public recording_URL, not the file itself. Supported protocols are http and ftp. Supported formats are .mp3, .mp4, .m4a, .wav, .ogg.
Accompaniment defines if the algorithm will try to discard instruments accompanying the singing voice. Level defines the level on which result timestamps will be produced - for each word or for each line. Note that if lrc lyrics format is selected, the line level does not make sense.
The end_times option toggles if end timestamp for each line/word will be output. Usually end line times make sense when having longer non-vocal intervals between the lines.
Upon creation of a new alignment, the status of the alignment is set to 1=NOT STARTED.
If recording_URL was provided, the actual alignment is started and the status of the alignment object is set to 2=ON_QUEUE. On successful upload, the response body contains the message “Alignment runs successfully!” in JSON format and the HTTP status code in the response header is 201 Created.
Needs authentication.
Lyrics could be given as either string or as a text file. If lyrics are given as a file, the post type should be ‘multipart/form-data’, otherwise ‘application/json’ is recommended. Meaningful lyrics lines are encouraged as they could help increase the alignment accuracy. One of lyrics_text, lyrics_file or composition_id has to be input. The lyrics_format is by default plain, which means only lyrics text. The lrc format stands for simple lrc - e.g. each lyrics line is prepended by a reference timestamp.
The audio file has to be passed as a public recording_URL, not the file itself. Supported protocols are http and ftp. Supported formats are .mp3, .mp4, .m4a, .wav, .ogg.
Accompaniment defines if the algorithm will try to discard instruments accompanying the singing voice. Level defines the level on which result timestamps will be produced - for each word or for each line. Note that if lrc lyrics format is selected, the line level does not make sense.
The end_times option toggles if end timestamp for each line/word will be output. Usually end line times make sense when having longer non-vocal intervals between the lines.
Upon creation of a new alignment, the status of the alignment is set to 1=NOT STARTED.
If recording_URL was provided, the actual alignment is started and the status of the alignment object is set to 2=ON_QUEUE. On successful upload, the response body contains the message “Alignment runs successfully!” in JSON format and the HTTP status code in the response header is 201 Created.
Needs authentication.
An example request (with lyrics file): curl --request POST --url http://api-demo.voicemagix.com/alignments/ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MjcyNzExODYsInVzZXJuYW1lIjoidGVzdHVzZXIifQ.k-kZb7iRevbDKRMm1sO-uu1snUTfsODIOhO862RI3AE' --header 'Content-Type: multipart/form-data' --form lyrics_file=@/workspace/test/example/umbrella_line.txt --form accompaniment=1 --form level=2’
An example of calling the method in postman can be found here
POST HTTP://API.VOICEMAGIX.COM/ALIGNMENTS/UPLOAD/
REQUEST BODY DATA (JSON) |
VALUE TYPE |
VALUE |
recording_URL |
Required. text |
- |
alignment_id |
Required. interger |
- |
Uploads the audio recording for an already requested alignment. This method is optional if uploading the recording_URL in the /alignments method failed or for whatever reason was not supplied. The audio file has to be passed as a public recording URL, not the file itself. Supported protocols are http and ftp. Supported formats are .mp3, .mp4, .m4a, .wav, .ogg.
On successful upload, the response body contains the message “Alignment runs successfully!” in JSON format and the HTTP status code in the response header is 201 Created.
If alignment_id does not exist, returns error code 404.
On upload the actual alignment is started and the status of the alignment object is updated from 1=NOT STARTED to 2=ON_QUEUE. Needs authentication.
On successful upload, the response body contains the message “Alignment runs successfully!” in JSON format and the HTTP status code in the response header is 201 Created.
If alignment_id does not exist, returns error code 404.
On upload the actual alignment is started and the status of the alignment object is updated from 1=NOT STARTED to 2=ON_QUEUE. Needs authentication.
An example request:
curl --request POST http://api-demo.voicemagix.com/alignments/upload/ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MjcyNzExODYsInVzZXJuYW1lIjoidGVzdHVzZXIifQ.k-kZb7iRevbDKRMm1sO-uu1snUTfsODIOhO862RI3AE' -H 'content-type: application/json' -F recording_url=http://my-website/media/recordings/umbrella_line.mp3 -F alignment_id=2
POST HTTP://API.VOICEMAGIX.COM/ALIGNMENTS/RUN/
REQUEST BODY DATA (JSON) |
VALUE TYPE |
VALUE |
alignment_id |
Required. interger |
- |
Triggers a re-alignment for an already requested alignment. The audio should have been uploaded already by the API call https://api.voicemagix.com/alignments/upload In case the upload API call had resulted in status=2 for longer time period,
this endpoint could be used to request a restart of the alignment. On success, the response body contains the message “Alignment runs successfully!”
this endpoint could be used to request a restart of the alignment. On success, the response body contains the message “Alignment runs successfully!”
GET HTTP://API.VOICEMAGIX.COM/ALIGNMENTS/<alignment_id>
Once the alignment status is ON_QUEUE (e.g. an audio recording has been uploaded), you need to wait (around 30 seconds for a track of 3 minutes) to finish the alignment.
On success, the response body is a JSON object with list of uploaded token timestamps (word timestamps or line timestamps) and the HTTP status code in the response header is 200 OK. if alignment_ID does not exist, return error code 404. When alignment is finished, if successful, the alignment status is 3=DONE, and timestamps have been added. If the status is 2=ON_QUEUE, this means that alignment is still in progress, so please try to access it again later. Status 4=FAILED means that the alignment is over but failed for the reason given in the field error_reason.
Needs authentication.
On success, the response body is a JSON object with list of uploaded token timestamps (word timestamps or line timestamps) and the HTTP status code in the response header is 200 OK. if alignment_ID does not exist, return error code 404. When alignment is finished, if successful, the alignment status is 3=DONE, and timestamps have been added. If the status is 2=ON_QUEUE, this means that alignment is still in progress, so please try to access it again later. Status 4=FAILED means that the alignment is over but failed for the reason given in the field error_reason.
Needs authentication.
An example request: curl --request GET --url http://api-demo.voicemagix.com/alignments/1 --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU0MDYwNjIsInVzZXJuYW1lIjoibWljaGFsIn0.FRDpwMCbAOFZDBOMyMb--25Qy1DdYSVbGznjec6Gydc'
