Timestamped Lyrics Alignment
Extract millisecond-accurate word and phrase timestamps for any Suno-generated audio track. Designed to power real-time karaoke teleprompters, synchronized music player lyric displays, social media short-form video subtitles, and automated LRC/SRT export.
Alignment Features & Applications
Word-Level PrecisionColor sweep animations in lockstep with the vocalist's vocal onset and duration.
Convert timestamps directly into industry-standard synced LRC or SubRip SRT subtitle files.
Includes pre-computed normalized audio peak data for instant canvas visualizer rendering.
Key Capabilities & Data Details
- Forced Phoneme Alignment: Maps vocal energy peaks and formant frequencies against the text script to ensure timestamps account for vocal melisma, vibrato, and held notes.
- Confidence Scoring: Each token returns a
palignvalue (0.0 to 1.0) indicating probabilistic alignment certainty. - Low Credit Cost: Consumes only 5 credits per alignment task.
Validation Rules & Constraints
Source Track Requirements
Both task_id and audio_id must point to an existing, non-instrumental music track generated with lyrics.
Asynchronous Webhook
Alignment processing takes several seconds. Configure callBackUrl to be notified as soon as word timestamps are ready.
Authentication & Headers
| Header | Requirement | Description |
|---|---|---|
| Authorization | required | Bearer YOUR_API_KEY Secret API key generated in your dashboard. |
| Content-Type | required | application/json Request body format. |
Request Body Parameters
4 fieldstask_idstringrequiredUnique identifier of the original music generation job containing the vocal performance.
audio_idstringrequiredUnique identifier (UUID) of the specific audio track within the generation task to align with lyrics.
taskTypestringoptionalExplicit task routing identifier. Can be set to "get_timestamped_lyrics".
callBackUrlstringoptionalPublic HTTPS webhook URL to receive asynchronous completion notification containing the aligned word timestamp array.
When Callbacks Are Sent
The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:
- Timestamp alignment task placed in acoustic phonetic decoder queue
- Vocal acoustic features extracted and aligned against lyric syllables
- Millisecond word boundaries and confidence alignment scores computed
- Webhook notification dispatched with alignedWords array and waveformData (code: 200)
Webhook Payload Format
{
"code": 200,
"msg": "All generated successfully.",
"data": {
"task_id": "3e63b4cc88d52611159371f6af5571e7",
"audio_id": "8ca376e7-5b62-49d9-bbd3-08aaf2c6dd27",
"alignedWords": [
{
"word": "[Verse 1]",
"success": true,
"startS": 1.25,
"endS": 1.68,
"palign": 0.98
},
{
"word": "Moonlight",
"success": true,
"startS": 1.72,
"endS": 2.45,
"palign": 0.99
},
{
"word": "spreads",
"success": true,
"startS": 2.5,
"endS": 2.98,
"palign": 0.97
},
{
"word": "across",
"success": true,
"startS": 3.02,
"endS": 3.42,
"palign": 0.96
},
{
"word": "the",
"success": true,
"startS": 3.45,
"endS": 3.6,
"palign": 0.99
},
{
"word": "windowsill",
"success": true,
"startS": 3.65,
"endS": 4.52,
"palign": 0.98
}
],
"waveformData": [
0.02,
0.15,
0.45,
0.82,
0.91,
0.65,
0.38,
0.12
],
"hootCer": 0.082,
"isStreamed": false
}
}Callback Payload Fields
| Field | Type | Description |
|---|---|---|
code | integer | HTTP status code (200: Success, 400: Bad Request, 500: Server error). |
msg | string | Execution status message ("All generated successfully." or error details). |
data.task_id | string | Unique task identifier corresponding to the alignment task. |
data.audio_id | string | Target audio track identifier that was analyzed. |
data.alignedWords | array | List of word objects containing word text, startS (start in seconds), endS (end in seconds), and palign (confidence score 0..1). |
data.waveformData | array | Normalized acoustic amplitude peak array suitable for rendering waveform visualizers. |
data.hootCer | number | Acoustic character error rate metric indicating alignment fidelity. |
Receiver Implementation Example
// Next.js App Router Webhook Receiver (/api/webhook/suno/route.ts)
import { NextRequest, NextResponse } from 'next/server';
export async function POST(req: NextRequest) {
const payload = await req.json();
const { code, msg, data } = payload;
if (code === 200 && Array.isArray(data?.alignedWords)) {
console.log(`Lyrics alignment for task ${data.task_id} completed!`);
console.log(`Total aligned words: ${data.alignedWords.length}`);
// Export to SRT / VTT subtitle format or synchronize karaoke player:
data.alignedWords.forEach((token: any) => {
console.log(`[${token.startS}s -> ${token.endS}s] ${token.word} (Confidence: ${token.palign})`);
});
// Store aligned words to database for real-time frontend playback highlighting
} else {
console.error(`Timestamped alignment failed (${code}): ${msg}`);
}
return NextResponse.json({ received: true });
}Webhook Security Recommendation
Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.
curl -X POST "https://api.sunoapi.top/api/v1/createTask" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"taskType": "get_timestamped_lyrics",
"task_id": "3e63b4cc88d52611159371f6af5571e7",
"audio_id": "8ca376e7-5b62-49d9-bbd3-08aaf2c6dd27",
"callBackUrl": "https://api.yourdomain.com/webhook/suno"
}'{
"code": 200,
"msg": "success",
"data": {
"taskId": "task_align_1740000000000_abc123"
}
}• Karaoke Engines: Use startS and endS to interpolate progress percentages for syllable-by-syllable lyric fills.
• Video Subtitles: Group words into sentences based on punctuation and line breaks for animated TikTok or YouTube Shorts captions.
• Pricing: 5 credits per alignment job.
Ready to extract millisecond lyric timestamps?
Generate your API key and align lyrics with synchronized audio playback in seconds.