가사 비디오 자동화

이 예제에서는 @youka/sdk 및 @youka/cli 0.2.0 이상을 사용하세요. API를 통해 생성된 프로젝트는 Youka 라이브러리에서 계속 사용할 수 있습니다.

워크플로와 모델 선택

kind는 프로젝트 워크플로를 선택합니다. karaoke는 스템을 분리합니다. lyric-video는 원본 오디오를 사용하며 분리 비용이 청구되지 않습니다. kind를 생략하면 기존의 karaoke 동작을 유지합니다. 가사 처리는 정렬(alignment), 전사(transcription), 또는 처리 없음 중에서 별도로 선택합니다. 모델을 선택하기 전에 모델을 탐색하고 계정의 사용 가능 여부를 확인하세요.

youka capabilities --json

const capabilities = await client.capabilities.get();
const eligibleModels = capabilities.models.filter(
  (model) => model.eligible && model.workflows.includes("lyric-video"),
);

응답에는 모델 ID, 작업(operation), 오디오 입력, 제공 텍스트 의미(supplied-text semantics), 워크플로, 언어 지원, 필요한 기능이 설명됩니다. suppliedTextHandling은 정렬, 제공자 keyterm, 전사 후 교정의 차이를 구분합니다. 사용 가능 여부(eligibility)는 인증된 계정을 반영합니다. 탐색 결과는 구성된 지원을 설명할 뿐, 제공자 가동 시간(uptime)을 보장하지 않습니다. 요청 검증과 가격 견적이 최종적으로 권위 있는 기준입니다. 분리된 보컬이 필요한 모델은 분리 없는 lyric video를 처리할 수 없습니다. 보컬을 생성하는 분리 모델을 사용하는 karaoke 워크플로에서 사용하세요. Wav2Vec2는 정렬 모델입니다. ElevenLabs Scribe는 전사 모델입니다. 전사 텍스트를 제공하는 것은 안내일 뿐, 출력 텍스트가 동일하다는 보장은 아닙니다.

프로젝트 생성 및 견적

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

const client = new YoukaClient({ apiKey: process.env.YOUKA_API_KEY! });
const operation = await client.projects.create(
  {
    kind: "lyric-video",
    source: { type: "path", path: "./song.wav" },
    title: "Example song",
    lyricsSource: {
      type: "transcribe",
      syncModel: AlignmentModel.ElevenLabsTranscription,
      lyrics: "Optional reference lyrics",
    },
  },
  { idempotencyKey: "example-song-create-v1" },
);
const { project } = await client.projects.wait(operation);

lyric video에 대해 광고된 모델로 제공된 가사를 정렬합니다.

youka project create ./song.wav --kind lyric-video --mode align \
  --sync-model audioshake-alignment --lyrics 'Line one
Line two' --json

karaoke 프로젝트에는 분리를 유지하세요. --kind를 생략하거나 --kind karaoke를 전달하고 --split-model을 선택하세요. 가사 처리 없이 생성하려면 --mode none을 사용하세요. lyric-video 요청은 분리 옵션을 거부합니다. 생성 전에 동일한 소스, 워크플로, 처리 옵션으로 견적을 확인합니다.

youka project quote ./song.wav --kind lyric-video --mode transcribe \
  --sync-model elevenlabs-transcription --json

견적은 생성과 동일하게 모델 호환성, 언어 정책, 계정 기능, 길이(duration), 저장소 규칙을 확인합니다. 크레딧 내역에서 lyric video는 분리 크레딧이 0입니다. 견적은 용량이나 크레딧을 예약하지 않으며, 생성 전에 계정 상태가 바뀔 수 있습니다.

처리 작업 없이 타이밍 수정

GET /projects/{projectId}/alignments로 정렬 목록을 읽고, 선택한 리소스는 GET /projects/{projectId}/alignments/{alignmentId}로 가져오세요. 목록에는 alignments, selectedAlignmentId, selectionRevision이 포함됩니다. 각 리소스에는 타이밍 payload, revision, selected, selectionRevision이 포함됩니다. 업데이트는 전체 alignment 객체를 완전히 교체합니다. 동기화를 실행하거나 처리 크레딧 홀드를 만들지 않습니다. 편집 시 ID, 텍스트, 줄/단어/서브워드 인덱스, 가수 정보, 번역을 유지하세요. 시간은 절대값의 소수 초(decimal seconds)입니다. 제출 값에는 원하는 교정을 한 번만 적용하세요. 내보내기 오프셋으로 동일한 교정을 다시 추가하지 마세요.

const snapshot = await client.projects.alignments.list(project.id);
const current = snapshot.alignments.find(
  (alignment) => alignment.id === snapshot.selectedAlignmentId,
);
if (!current) throw new Error("Project has no alignment to edit");

const corrected = structuredClone(current.alignment);
corrected.items[0]!.start = 0.75;
corrected.items[0]!.end = 1.25;

const saved = await client.projects.alignments.update(project.id, current.id, {
  alignment: corrected,
  expectedRevision: current.revision,
  select: true,
  expectedSelectionRevision: snapshot.selectionRevision,
});

select: true를 사용하면 저장과 선택을 원자적으로(atomic) 수행합니다. 기존 타이밍을 교체하지 않고 선택만 하려면 client.projects.alignments.select(projectId, alignmentId, { expectedRevision, expectedSelectionRevision })를 호출하세요. 정렬 revision은 타이밍 내용(contents)을 보호합니다. selection revision은 어떤 정렬이 활성(active)인지 보호합니다. 오래된 토큰은 HTTP 409를 발생시킵니다. 최신 리소스를 가져와 편집 내용을 비교한 뒤, 의도적인 교체를 제출하세요. 토큰을 자동으로 갱신해 다른 편집자의 변경을 덮어쓰지 마세요. CLI는 JSON 파일 또는 표준 입력을 받습니다. 가져오기 파일에는 { "alignment": { "items": [...] }, "expectedRevision": "..." }가 포함됩니다. 원자적으로 선택하려면 select와 expectedSelectionRevision을 포함하세요. 내보낸 리소스에는 응답 메타데이터도 포함되므로, 가져오기 전에 요청 필드를 추출하세요.

youka project timings list proj_example --json
youka project timings get proj_example aln_example --json > timing-resource.json
youka project timings import proj_example aln_example --body corrected-request.json --json
youka project timings select proj_example aln_example \
  --expected-revision "$ALIGNMENT_REVISION" \
  --expected-selection-revision "$SELECTION_REVISION" --json

가져오기는 최대 100,000개 항목을 허용합니다. 모든 종료 시간은 시작 시간보다 엄격히 커야 합니다. 잘못된 숫자, 음수 시간, 잘못된 인덱스, 길이가 0이거나 역전된 범위, 알려진 프로젝트 길이를 초과하는 타이밍은 거부됩니다. 유효한 겹침(overlaps)과 듀엣 타이밍은 계속 지원됩니다. 외부 편집 후에는 이미 열려 있는 앱 프로젝트를 다시 열거나 새로고침하세요.

선택한 버전 내보내기

youka project versions proj_example --json
youka export create proj_example --version-id ver_example --local \
  --transparent --mute-all --fps 30 --output ./overlay.mov --json

versionId는 내보내기 요청과 설정 업데이트, 그리고 설정 GET 쿼리에서 선택 사항입니다. 이를 생략하면 기본 버전(primary-version) 동작을 유지합니다. 선택된 정렬은 프로젝트에 속하고, 스타일링과 설정은 선택한 버전에 속합니다.

const versions = await client.projects.versions.list(project.id);
const versionId = versions[0]!.id;
const stemVolumes = Object.fromEntries(
  project.stems.map((stem) => [stem.id, 0]),
);
const payload = await client.exports.prepareLocal(project.id, {
  versionId,
  transparent: true,
  stemVolumes,
  fps: 30,
});
console.log(payload.versionId, payload.alignmentId, payload.alignmentRevision);

await client.exports.create(project.id, {
  target: "local",
  versionId,
  transparent: true,
  stemVolumes,
  fps: 30,
  outputPath: "./overlay.mov",
});

클라우드 내보내기 operation handle과 로컬 payload에는 versionId, alignmentId, alignmentRevision이 포함됩니다. 이 필드들은 해당 내보내기 또는 준비된 payload에 사용된 타이밍 스냅샷을 식별합니다. 각 준비(preparation)는 현재 상태를 읽으므로, 나중에 별도로 수행되는 내보내기는 더 최신 편집을 관찰할 수 있습니다. 외부 렌더러가 준비된 스냅샷을 정확히 렌더링해야 한다면 반환된 payload를 저장하고, 서명된 미디어 URL이 만료되면 이를 새로고침하세요. 투명(transparent) 로컬 출력은 MOV 컨테이너의 ProRes 4444를 사용합니다. --mute-all은 모든 프로젝트 스템을 볼륨 0으로 매핑합니다. 무음(silence)과 오디오 스트림 부재는 서로 다른 출력 속성입니다. 다운스트림 도구가 둘 중 하나를 요구한다면 렌더링된 파일을 검사하세요. 로컬 렌더링은 클라우드 내보내기 크레딧을 소비하지 않으며, 기존 기능 사용 가능 조건의 적용을 받습니다. 단어 타이밍, 전역 오디오 오프셋, 가사 선행(lyric anticipation)은 서로 다른 설정입니다. 기존 레이아웃은 줄 표시 여부를 제어합니다. 이 릴리스는 모든 줄에 대해 고정된 공개(reveal) 간격을 보장하지 않으며, 별도의 반주 트랙(backing-track) 첨부 API를 추가하지도 않습니다.

카탈로그를 안전하게 운영

안정적인 항목 ID, 소스 지문(fingerprint), 작업 설정, 멱등성 키(idempotency key), 프로젝트/태스크 ID, 마지막 최종 결과(terminal result)를 포함한 매니페스트를 유지하세요. 동일한 키는 같은 요청을 재시도할 때만 재사용하세요. 재시작 시 폴링을 재개할 수 있도록 완료를 기다리기 전에 생성 결과를 영속화하세요. 업로드와 로컬 파일 준비는 각각의 라이프사이클이 있으며, create 멱등성 키가 모든 업로드를 중복 제거(deduplicate)하지는 않습니다. 실행 가능한 catalogue example은 사전 업로드된 입력 파일 ID를 받아들이고 항목당 체크포인트를 1개씩 저장합니다. 매니페스트는 다음과 같습니다.

[
  {
    "id": "song-001",
    "request": {
      "kind": "lyric-video",
      "inputFileId": "owned-upload-id",
      "title": "Example song",
      "lyricsSource": {
        "type": "transcribe",
        "syncModel": "elevenlabs-transcription"
      }
    }
  }
]

예제를 catalogue.ts로 다운로드하세요. 의존성을 설치하고 YOUKA_API_KEY를 설정하세요. package.json에 "type": "module"이 있는 Node.js 프로젝트를 사용하세요.

npm install @youka/sdk@^0.2.0 tsx
npx tsx ./catalogue.ts ./manifest.json ./catalogue-state 1

같은 매니페스트와 상태 디렉터리로 다시 실행하면, 승인된 작업을 폴링 중인 상태에서 재개하거나 원래 키로 불확실한 제출을 재시도할 수 있습니다. 완료 및 실패한 작업은 기록되고 건너뜁니다. 변경된 요청에는 새 항목 ID가 필요합니다. 디렉터리 락은 두 프로세스가 같은 매니페스트를 동시에 제출하는 것을 방지합니다. 하드 크래시 후에는, 그 안에 저장된 PID가 더 이상 실행 중이 아님을 확인한 다음에만 오래된 .lock을 제거하세요. 진행 중(in-flight) 항목 1개로 시작하세요. 계정에 대한 처리 지연과 rate-limit 응답을 측정한 뒤에만 제한된 워커 수를 늘리세요. Retry-After를 준수하면서 백오프(backoff)로 전송 오류와 rate limit을 재시도하세요. 검증 오류, 타이밍 충돌, 최종 처리 실패(terminal processing failures)는 무작정 재시도하지 마세요. 인증 오류는 유효한 자격 증명이 필요하다는 뜻이며, 처리 작업이 실패했다는 의미가 아닙니다. 기존의 클라우드 태스크 폴링과 실패 크레딧 처리(failure-credit handling)를 유지하세요. 여기에서는 배치 엔드포인트, 웹훅 보장, 가격 변경, 라이선스 변경, 보존 정책(retention policy)을 새로 도입하지 않습니다.

Guides

API Reference

가사 비디오 자동화

워크플로와 모델 선택

프로젝트 생성 및 견적

처리 작업 없이 타이밍 수정

선택한 버전 내보내기

카탈로그를 안전하게 운영

​워크플로와 모델 선택

​프로젝트 생성 및 견적

​처리 작업 없이 타이밍 수정

​선택한 버전 내보내기

​카탈로그를 안전하게 운영

워크플로와 모델 선택

프로젝트 생성 및 견적

처리 작업 없이 타이밍 수정

선택한 버전 내보내기

카탈로그를 안전하게 운영