This documentation describes how to use the API for transcription services offered by PianoConvert. It covers the process from authentication to file upload and receiving notifications about the transcription status.

1. Authentication

To authenticate, you need to make a POST request to the following URL with three parameters: email, companyName, and endPoint. The email will be used to identify yourself, and the endpoint is your URL to receive notifications from our API.

URL: https://pianoconvert.latouchemusicale.com/api/company-signup

Example Request in Node.js:

const axios = require('axios');

const login = async (email, companyName, endPoint) => {
  try {
    const response = await axios.post('https://pianoconvert.latouchemusicale.com/api/company-signup', {
      email: email,
      companyName: companyName,
      endPoint: endPoint
    });
    const token = response.data.token;
    console.log('Your token:', token);
    return token;
  } catch (error) {
    console.error('Error logging in:', error);
  }
};

const email = 'your-email@example.com';
const companyName = 'your company name';
const endPoint = 'your-endpoint-url';
login(email, companyName, endPoint);

Example Response:

{
  "token": "your-unique-token"
}

The response will give you a token, which you have to save for future requests. In case you lose your token, just repeat the request to get a new token.

 

2. Transcription Credits

To perform transcriptions, you will need transcription credits on your PianoConvert developer account. As part of your integration tests with the PianoConvert API, we offer you 20 free credits. To receive them, please send us an email at contact@latouchemusicale.com after your authentication so that we can credit your account immediately.

If you proceed to the next step without being credited beforehand, you will receive the following error:

{
   "status": 402,
   "text": "You have reached your maximum use of transcriptions, reload your credits for more"
}

3. Get Upload URL

To start a transcription, you need to POST to the following URL with parameters author and title, including the previously received token in the Bearer authorization header.

URL: https://pianoconvert.latouchemusicale.com/api/get-upload-url

Example Request in Node.js:

const transcribe = async (token, author, title) => {
  try {
    const response = await axios.post('https://pianoconvert.latouchemusicale.com/api/get-upload-url', {
      author: author,
      title: title
    }, {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    const uploadUrl = response.data.uploadUrl;
    const transcriptionId = response.data.id;
    console.log('Upload URL:', uploadUrl);
    console.log('Transcription ID:', transcriptionId);
    return { uploadUrl, transcriptionId };
  } catch (error) {
    console.error('Error starting transcription:', error);
  }
};

const token = 'your-token';
const author = 'author-name';
const title = 'title-of-the-piece';
transcribe(token, author, title);

Example Response:

{
    "text": "url founded",
    "idTranscription": "66683ba9026b1536f661e854",
    "signedUrl": "https://s3.eu-west-3.amazonaws.com/music-convert.latouchemusicale/payed/mp3/66680c4c7b5f629a5d24d597_66683ba9026b1536f661e854.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4HLDUL7J3ESGLCXU%2F20240611%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20240611T115729Z&X-Amz-Expires=36000&X-Amz-Signature=49de1c67dc8de458afac4817c83bdf8d30cb80c74bf431dde33bb5df5b003a67&X-Amz-SignedHeaders=host"
}

The ID returned in the response should be saved, as it will allow you to identify the transcription in the notifications you receive from the API at step 5 of this documentation.

4. Upload File

After receiving the upload URL from the transcription request, you need to upload your file to the provided AWS S3 URL.

Example Request in Node.js:

const fs = require('fs');
const axios = require('axios');

const uploadFile = async (uploadUrl, filePath) => {
  try {
    const fileStream = fs.createReadStream(filePath);
    const response = await axios.put(uploadUrl, fileStream, {
      headers: {
        'Content-Type': 'audio/mp3' // Adjust the content type based on the file format
      }
    });
    console.log('File uploaded successfully:', response.status);
  } catch (error) {
    console.error('Error uploading file:', error);
  }
};

const uploadUrl = 'your-upload-url';
const filePath = 'path/to/your/file.mp3';
uploadFile(uploadUrl, filePath);

5. Transcription & Notifications

For each step of the transcription, you will receive notifications at the endpoint you provided in the first request. The different notifications will be:

- step 2 : “File uploaded successfully” 

- step 4 : “File converted to MIDI"

- step 5 : “MIDI, PDF, and MusicXML are ready to be downloaded”

- step 6 :“There was an error in our conversion. Verify the quality of the file.”

Example Notification Format:

{
  "step": 5,
  "text": "Midi, pdf and musicxml are ready to be downloaded.",
  "idTranscription": "transcription-id",
  "url_get_pdf": "https://s3.eu-west-3.amazonaws.com/music-convert.latouchemusicale/pdf/your-file.pdf",
  "url_get_midi": "https://s3.eu-west-3.amazonaws.com/music-convert.latouchemusicale/midi/your-file.midi",
  "url_get_musicxml": "https://s3.eu-west-3.amazonaws.com/music-convert.latouchemusicale/xml/your-file.xml"
}

6. Downloading Files

When the files are ready, you will receive AWS URLs to download the files.

Example URLs:

- PDF: https://s3.eu-west-3.amazonaws.com/music-convert.latouchemusicale/pdf/your-file.pdf

- MusicXML: https://s3.eu-west-3.amazonaws.com/music-convert.latouchemusicale/sheet-music/your-file.musicxml

- MIDI: https://s3.eu-west-3.amazonaws.com/music-convert.latouchemusicale/payed/midi-separated/your-file.mid

 

7. Pricing information

We encourage you to first test the API with your 20 free credits provided with your Discovery Plan. If you are satisfied with the results and the functionality of our API, you can then choose the plan that best suits your needs:

Enterprise Pricing Plans:

• Starter Plan: €99/month for 500 transcriptions
• Advanced Plan: €299/month for 2,000 transcriptions
• Pro Plan: €499/month for 4,000 transcriptions

Please find below the detailed pricing for our enterprise plans for using our API:

Once you have chosen your plan, please send us an email at contact@latouchemusicale.com so we can proceed with the payment (credit card or PayPal) and credit your enterprise account.

8. Contact

If you have any questions, feel free to contact us at contact@latouchemusicale.com at any time.