Lyric Studio

가사 비디오를 만들기 위한 도구입니다: 배경 이미지 + 오디오 트랙, 그리고 선택한 정확한 타임스탬프에 나타나고 사라지는 가사 줄을 어떤 실제 Google Font로도 만들 수 있습니다.

같은 프로젝트를 공유하는 두 부분으로 구성됩니다:

• 편집기 UI — 브라우저에서 열어 미디어를 업로드하고, 가사 줄과 타이밍을 입력하고, 글꼴/색상을 선택하고, 렌더링하는 웹 앱입니다.

• MCP 서버 — 같은 프로젝트를 도구로 노출하여 AI 어시스턴트(Claude Desktop, Claude Code 등)가 대신 가사 줄을 추가/편집하고 렌더링을 트리거할 수 있게 합니다.

둘 다 동일한 projects/default/project.json을 공유하므로, AI가 추가한 줄은 브라우저 UI에 표시되고(5초마다 폴링), 그 반대도 마찬가지입니다.

요구 사항

• Node.js 18+

• PATH에 ffmpeg 및 ffprobe (ffmpeg -version으로 확인)

• 인터넷 접속(각 글꼴을 처음 사용할 때 Google Fonts를 다운로드하기 위해)

Related MCP server: Music Media MCP Server

설정

npm install

1. 편집기 UI 실행

npm run start

그런 다음 http://localhost:4790 을 엽니다.

UI에서:

1. 오디오 파일을 추가합니다.

2. 배경 이미지를 하나 이상 추가합니다. 각 이미지에 대해 이미지 시퀀스에 추가를 클릭하기 전에 "until" 상자에 재생 시간을 입력합니다(예: 3:00) — 이미지는 추가한 순서대로 연속 재생됩니다. 마지막 이미지의 "until"은 비워 두면 노래 끝까지 재생됩니다. 2개의 이미지가 있는 4분짜리 노래의 예: 이미지 1을 until: 3:00으로 추가한 다음, 이미지 2는 until을 비워 둡니다(자동으로 4:00까지 재생됨).

3. Google Font, 크기, 색상, 윤곽선, 위치(상단/중간/하단)를 선택합니다.

4. 가사 줄을 추가합니다: 텍스트 + 시작 시간 + 종료 시간(3:05, 185, 또는 1:03:05 모두 가능). 타임라인에서 가사 블록을 드래그하여 타이밍을 이동하거나, 왼쪽/오른쪽 가장자리를 드래그하여 시작 또는 끝만 조정할 수 있습니다 — 놓으면 자동으로 저장됩니다.

5. 타임라인을 스크러빙하여 특정 시점에 어떤 줄과 어떤 이미지가 표시되는지 미리 봅니다.

6. Render video를 클릭합니다 — 완료되면 MP4가 다운로드 링크와 함께 나타납니다.

2. MCP 서버 실행 (AI 제어용)

MCP 서버는 stdio로 통신하므로, 직접 실행하는 대신 AI 도구의 설정에서 이를 가리키면 됩니다.

Claude Desktop / Claude Code — MCP 설정에 추가합니다(claude_desktop_config.json 또는 이에 상응하는 파일):

{
  "mcpServers": {
    "lyric-studio": {
      "command": "node",
      "args": ["/absolute/path/to/lyric-video-mcp/mcp-server.js"]
    }
  }
}

클라이언트를 다시 시작하면 AI가 다음 도구를 사용할 수 있습니다:

노래의 각 섹션에 여러 이미지 사용

이미지는 추가한 순서대로 연속 재생됩니다 — 각 이미지는 이전 이미지가 끝난 지점부터 지정한 until 시간까지 재생됩니다:

오디오를 /Users/me/song.mp3로 설정합니다(4분 길이). /Users/me/cover1.jpg를 until "3:00"으로 추가합니다. 그런 다음 /Users/me/cover2.jpg를 "until" 없이 추가합니다 — 끝까지 재생되어야 합니다.

결과: cover1.jpg는 0:00–3:00, cover2.jpg는 3:00–4:00. 이 방식으로 원하는 만큼 이미지를 추가할 수 있습니다 — 각 새 이미지는 자체 until만 있으면 됩니다. 이미지가 오디오 길이를 완전히 덮지 않으면 렌더링이 명확한 오류와 함께 실패하므로, 빈 구간을 채워야 하는지 알 수 있습니다.

연결 후 AI에 보내는 예시 프롬프트

lyric-studio를 사용하세요: 이미지를 /Users/me/cover.jpg로, 오디오를 /Users/me/raikan-cinta.mp3로 설정합니다. "Poppins" 글꼴을 흰색에 검은 윤곽선, 하단 위치로 사용합니다. 이 가사 줄을 추가합니다: "Mari mawar raikan cinta, tanpa cintanya kita tiada, mawar cinta mawar ku abadi, cinta pemilik segala jadi" 3:05부터 3:35까지. 그런 다음 렌더링합니다.

렌더링 작동 방식

가사 줄은 .ass 자막 파일로 변환되어 ffmpeg/libass로 비디오에 굽혀지며, 실제 Google Font TTF(fonts-cache/에 다운로드 및 캐시됨)를 사용합니다 — 일반 시스템 글꼴 대체가 아닙니다.

프로젝트 구조

shared/projectStore.js   core logic — used by BOTH the UI server and MCP server
shared/fonts.js          Google Fonts catalog + real TTF downloader
shared/timeUtils.js      "3:05" / "185" / "1:03:05" time parsing
ui-server.js             Express server + REST API for the browser UI
mcp-server.js            MCP server (stdio) for AI control
public/                  browser UI (index.html, style.css, app.js)
projects/default/        this project's media, generated .ass file, project.json
fonts-cache/             downloaded Google Font TTF files (cached after first use)
public/output/           rendered MP4s

참고 사항

• 이 도구는 설계상 단일 프로젝트 도구입니다(활성 프로젝트가 하나, default임) — "노래 하나, 비디오 하나" 사용에 가장 적합합니다. 여러 동시 프로젝트가 필요하다면, shared/projectStore.js의 모든 함수는 이미 projectId를 받으므로 두 서버를 통해 다른 ID를 전달하는 것은 작은 변경입니다.

• 글꼴 파일은 첫 다운로드 후 캐시되므로, 같은 글꼴로 다시 렌더링해도 네트워크에 다시 접근하지 않습니다.