@youka/sdk

Official Node.js SDK for the Youka API.

Use this package to create karaoke videos from Node.js: upload audio or video, sync or transcribe lyrics, create a karaoke project, render the final video, and download the MP4.

Install

npm install @youka/sdk

API key

Create an API key at online.youka.io/account under API keys.

Keep the key outside your source code:

export YOUKA_API_KEY="yk_..."

Create a karaoke video

import { YoukaClient } from "@youka/sdk";

const client = new YoukaClient({
  apiKey: process.env.YOUKA_API_KEY!,
});

const operation = await client.projects.create({
  source: {
    type: "path",
    path: "./song.mp3",
  },
  lyricsSource: {
    type: "align",
    text: "Line one\nLine two\nLine three",
  },
  title: "Artist - Song",
});

const { project } = await client.projects.wait(operation);

const exportOperation = await client.exports.create(project.id, {
  resolution: "1080p",
  quality: "high",
});

const finalized = await client.exports.wait(exportOperation);

await client.exports.download(finalized, {
  output: "./karaoke.mp4",
});

Transcribe lyrics automatically

Use transcription when you do not already have lyrics text:

const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe" },
  title: "Artist - Song",
});

Use a hosted media URL

You can also create a karaoke video from a hosted media URL:

const operation = await client.projects.create({
  source: {
    type: "url",
    url: "https://example.com/song.mp4",
  },
  lyricsSource: {
    type: "align",
    text: "Line one\nLine two",
  },
});

URL helpers automatically ensure the local download binaries on first use. Supported hosted sites depend on yt-dlp: https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md

Handle errors

import { YoukaRequestError, YoukaTaskError } from "@youka/sdk";

try {
  const operation = await client.projects.create({
    source: { type: "path", path: "./song.mp3" },
    lyricsSource: { type: "transcribe" },
  });

  await client.projects.wait(operation);
} catch (error) {
  if (error instanceof YoukaRequestError) {
    console.error(error.code, error.status, error.message);
  } else if (error instanceof YoukaTaskError) {
    console.error(error.code, error.status, error.message);
  } else {
    throw error;
  }
}

Docs

• Node.js SDK guide: https://docs.youka.io/en/sdk
• Raw HTTP quickstart: https://docs.youka.io/en/api/quickstart
• CLI guide: https://docs.youka.io/en/cli