Voice Magix
  • Home
  • Solutions
  • API
  • About
  • Contact

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 info@voicemagix.com  

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 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?asdasd
A: We license the API offering two different pricing options: per-minute of audio content processed or as a monthly subscription plan. For a subscription, you can use the server unlimited time. The pricing varies according to the duration of the subscription plan (a minimum of 3 months). Additionally, the subscription plan includes support for issues, whereas per-minute plan does not. For concrete prices, please contact sales@voicemagix.com  
 
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 (by default two weeks). You need to pick up one of the test users and use the endpoint auth/token to generate a token, which can be used to authenticate you in subsequent calls to the API.  

Q: Calling the auth/token endpoint I keep getting "Invalid credentials. Please try again!” even though my credentials are correct?
A: Make sure that the content type is not “multipart/form-data”. “multipart/form-data” is needed only for the if you are uploading a lyrics_file on the alignments endpoint. Otherwise use 

Endpoints Description

​POST HTTP://API.VOICEMAGIX.COM/AUTH/TOKEN

​REQUEST BODY DATA (JSON)
​VALUE TYPE
VALUE
username
Required. string
-
​password
Required. string
-
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.   
An example request: curl --request POST --url https://api.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 https://api.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 string.
​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
​​accompaniment
Required. integer
{1,2} 1=acapella, 2=multi-instrumental
level
integer

{1,2}, 1=words, 2=lines.  default= 1
title
string. 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
integer
-
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 given. 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. 

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.
An example request (with lyrics file): curl --request POST --url https://api.voicemagix.com/alignments/ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MjcyNzExODYsInVzZXJuYW1lIjoidGVzdHVzZXIifQ.k-kZb7iRevbDKRMm1sO-uu1snUTfsODIOhO862RI3AE' --header 'Content-Type: multipart/form-data' --form lyrics=@/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

recording_URL
Required. string
-
alignment_id
Required. integer
-
Uploads the audio recording for an already requested alignment.  On success, the response body contains the message “Audio uploaded successfully!” in JSON format and the HTTP status code in the response header is 201 Created. Supported formats are .mp3, .mp4, .m4a, .wav, .ogg.  If alignment_id does not exist, returns error code 404. Please avoid uploading long files in .wav format because the upload could fail with http timeout due to their big size.   

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 https://api.voicemagix.com/alignments/upload -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MjcyNzExODYsInVzZXJuYW1lIjoidGVzdHVzZXIifQ.k-kZb7iRevbDKRMm1sO-uu1snUTfsODIOhO862RI3AE' -H 'content-type: application/json' -F recording_url=http://127.0.0.1:8000/media/recordings/umbrella_line.mp3 -F alignment_id=2

​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 50 seconds for a track of 5 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 again later. Status 4=FAILED means that there the alignment is over but failed for the reason given in the field error_reason. Needs authentication.
An example request: curl --request GET --url https://api.voicemagix.com/alignments/1 --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU0MDYwNjIsInVzZXJuYW1lIjoibWljaGFsIn0.FRDpwMCbAOFZDBOMyMb--25Qy1DdYSVbGznjec6Gydc'

Contact Us


Supported by

Picture
Picture
Picture
  • Home
  • Solutions
  • API
  • About
  • Contact