# 동영상 오버레이

> 동영상 위에 이미지를 최대 20개까지 각자의 시간대에 표시하세요. 카드, 코너 배지, 전체 화면, 사용자 지정 상자로 배치하고, 실시간 미리 보기와 원래 오디오가 유지됩니다.

Source: https://nodaro.ai/ko/docs/nodes/video/video-overlay

**동영상 오버레이** 노드는 동영상 위에 이미지를 각자의 시간대 동안 표시합니다. 로고, 제품 사진, 스크린샷, 내레이션에 맞춘 카드에 사용하세요. 노드는 내 이미지 파일을 그대로 동영상 위에 그리고, 원래 오디오를 유지하며, 노드에 실시간 미리 보기를 보여 줍니다. 이 모든 것을 AI 모델 없이 처리합니다.

- Found in: Video › Titles, Graphics & Captions
- API type: `video-overlay`

## 사용 시기
- UGC 광고를 만들면서, 화자가 언급하는 순간에 제품 카드, 앱 스크린샷, 웹 페이지가 나타나게 하고 싶을 때.
- 동영상 전체에 걸쳐 로고나 채널 핸들을 화면에 띄우고 싶을 때.
- 화면 속 화면 스틸, 비포 앤 애프터 이미지, 리액션 이미지를 넣고 싶을 때.
- 제품 클립 위에 가격표나 “신제품” 배지를 얹고 싶을 때.

## 빠른 시작
### 노드 추가
캔버스에서 Tab을 누르고 **동영상 › 타이틀, 그래픽 및 자막 › 동영상 오버레이**를 선택하세요.

### 동영상과 이미지 연결
기본 동영상을 **동영상** 입력에 연결하세요. 각 이미지는 **레이어 1**, **레이어 2**처럼 각자의 레이어 핸들에 연결하세요. 노드는 레이어 핸들 4개로 시작합니다.

### 레이어별 시간과 위치 지정
설정 패널을 여세요. 레이어마다 <strong>시작(초)</strong>와 <strong>끝(초)</strong>를 설정한 뒤 **배치**를 선택하세요. 노드의 미리 보기에서 레이어를 끌어 옮기거나, 모서리 핸들을 당겨 크기를 바꾸세요.

### 실행
**실행**을 클릭하세요. 노드가 모든 레이어를 각자의 시간대에 넣어 동영상을 렌더링합니다. 미리 보기 라벨이 **미리 보기**에서 **결과**로 바뀝니다.

Workflow: 스크린샷이 카드로 튀어나오고 로고는 모서리에 머뭅니다. 그 위에 자막을 넣은 뒤 동영상을 게시합니다.

- 동영상 업로드 → 동영상 오버레이 (동영상)
- 이미지 업로드 → 동영상 오버레이 (레이어 1)
- 이미지 업로드 → 동영상 오버레이 (레이어 2)
- 동영상 오버레이 → 자막 추가 (동영상)
- 자막 추가 → TikTok 게시물

## 입력
| 입력 | 받는 노드 | 하는 일 |
| --- | --- | --- |
| **동영상** | 동영상 업로드, 동영상 생성 같은 동영상 노드 | 기본 동영상입니다. 필수입니다. |
| **레이어 1**~**레이어 12** | 이미지 업로드, 이미지 생성, 이미지 오버레이 같은 이미지 노드 | 레이어마다 이미지 하나입니다. 레이어 1이 첫 번째 핸들, 레이어 2가 두 번째 핸들이며, 이런 식으로 이어집니다. |
| **레이어 플랜** | JSON 레이어 목록 | 선택 사항입니다. 각자 이미지 URL을 가진 타이밍 레이어를 더 추가합니다. [레이어 플랜 입력](#layer-plan-input)을 참조하세요. |

출력인 **동영상**은 레이어를 그려 넣은 동영상으로, MP4입니다.

설정 패널의 **+ 레이어**와 **− 레이어** 버튼으로 레이어 핸들을 1~12개 표시하세요. 더 높은 번호의 핸들에 연결하면 개수도 저절로 늘어납니다.

### 레이어 플랜 입력
**레이어 플랜** 입력은 노드 자체의 레이어 형식으로 된 JSON 레이어 목록을 받습니다. 형식은 `imageUrl`, `start`, `end`와 상자 필드 `anchor`, `x`, `y`, `width`, `height`, `fit`입니다. 예를 들어 스크린샷 카드를 보이스오버에 맞춰 배치하는 노드와 함께 쓰세요.

- **플랜 레이어는 핸들 레이어 아래에 그려집니다.** 그래서 핸들에 연결한 로고 배지가 위에 남습니다.
- **플랜 레이어마다 자체 `imageUrl`이 필요합니다.** 플랜 레이어는 핸들에서 이미지를 가져오지 않습니다. 이미지가 없는 플랜 레이어는 “Plan layer 1: no image — set imageUrl on this layer in the plan.”(플랜 레이어 1: 이미지 없음 — 플랜에서 이 레이어에 imageUrl을 설정하세요) 메시지와 함께 실패합니다.
- **플랜 레이어도 한도에 포함됩니다.** 플랜 레이어와 핸들 레이어를 합쳐 최대 20개입니다.
- **미리 보기에 플랜 레이어가 표시됩니다.** 읽기 전용 레이어로, **레이어 플랜에서**라고 표시됩니다.
- **빈 플랜은 동영상을 그대로 통과시킵니다.** 레이어 플랜이 연결되어 있고 그릴 레이어가 없으면, 노드는 동영상을 바꾸지 않고 비용 없이 출력합니다.

## 실시간 미리 보기
기본 동영상을 연결하면 노드가 그 동영상의 한 프레임을 보여 주고, 렌더링 때 놓일 위치에 레이어를 그려 줍니다.

- **레이어 선택**: 설정 패널의 **타임라인**에서 레이어의 막대를 클릭하세요. 미리 보기가 그 레이어의 시작 지점으로 이동하고, 그 순간에 보이는 레이어만 보여 줍니다.
- **레이어 끌기**: 레이어를 끌어 옮기고, 모서리 핸들을 당겨 크기를 바꾸세요. 끌 때마다 새 백분율이 레이어 설정에 기록되므로, 미리 보기와 실행이 같은 숫자를 사용합니다.
- **결과 또는 결과(이전).** 실행 후 노드에는 **결과**가 표시됩니다. 그 뒤에 레이어를 옮기거나 다른 이미지를 연결하는 등 설정을 바꾸면, 다시 실행할 때까지 라벨이 <strong>결과(이전)</strong>으로 표시됩니다.

## 레이어 설정
설정 패널에서 레이어마다 **레이어 1**, **레이어 2** 같은 제목이 붙은 카드가 있습니다.

| 설정 | 하는 일 |
| --- | --- |
| **시작(초)** | 레이어가 나타나는 시점으로, 동영상 시작부터의 초입니다. 기본값은 `0`입니다. |
| **끝(초)** | 레이어가 사라지는 시점입니다. <strong>시작(초)</strong>보다 뒤여야 합니다. 비워 두면 동영상이 끝날 때까지 레이어를 표시합니다. |
| **배치** | **카드**, **코너 배지**, **전체 화면**, **사용자 지정** 중 하나입니다. 연결만 하고 바꾸지 않은 레이어는 동영상 전체에 걸쳐 오른쪽 아래 코너 배지가 됩니다. |
| **모서리** | **코너 배지**용입니다. **왼쪽 위**, **오른쪽 위**, **왼쪽 아래**, **오른쪽 아래**(기본값) 중 하나입니다. |
| **기준점**, **오프셋 X**, **오프셋 Y**, **너비**, **높이(프레임 대비 %, 선택 사항)**, **맞춤(높이 지정 시)** | **사용자 지정**용입니다. [사용자 지정 상자](#custom-boxes)를 참고하세요. |
| **레이어 순서(z)** | 0~100입니다. 값이 높은 레이어가 위에 그려집니다. 비워 두면 레이어 번호를 쓰므로, 레이어 1이 맨 아래에 놓입니다. 미리 보기의 위아래 버튼으로도 설정할 수 있습니다. |
| **불투명도** | 0~100%입니다. 기본값은 100%입니다. |
| **등장/퇴장 애니메이션** | 기본적으로 켜져 있습니다. 레이어가 0.15초 동안 크기의 96%에서 100%로 커지면서 서서히 나타나고, 끝날 때는 그 반대로 사라집니다. |

### 배치
모든 위치와 크기는 출력 프레임에 대한 백분율입니다.

| 배치 | 레이어가 놓이는 위치 |
| --- | --- |
| **카드** | 가운데에서 4% 위쪽에, 프레임의 78% × 60% 안에 맞춰 놓입니다. 이미지는 화면 비율을 유지합니다. |
| **코너 배지** | 프레임 너비의 18% 크기로, 선택한 모서리에서 4% 안쪽에 놓입니다. |
| **전체 화면** | 프레임 전체를 덮습니다. 이미지는 프레임을 채우도록 잘립니다. |
| **사용자 지정** | 내가 정한 상자입니다. |

**카드**는 프레임 가운데에 놓이며, 9:16 셀카 동영상에서는 화자의 얼굴 위입니다. 이는 의도된 것으로, 말하는 사람 위로 제품 카드가 튀어나오게 합니다. 피사체를 가리면 안 되는 로고나 배지는 코너 배지나 사용자 지정 상자에 넣으세요.

### 사용자 지정 상자
- **기준점**은 레이어가 붙는 프레임 위의 아홉 위치 중 하나입니다.
- **오프셋 X**와 **오프셋 Y**는 기준점에서 레이어를 옮기며, 프레임 너비와 높이의 -100~100%입니다. 오른쪽이나 아래쪽 기준점에서 음수 오프셋을 주면 레이어가 안쪽으로 이동합니다.
- **너비**는 프레임 너비의 1~100%입니다.
- <strong>높이(프레임 대비 %, 선택 사항)</strong>은 프레임 높이의 1~100%입니다. 지정하지 않으면 높이는 이미지의 화면 비율을 따릅니다.
- <strong>맞춤(높이 지정 시)</strong>는 이미지가 상자를 채우는 방식을 정합니다. **전체 표시**는 이미지 전체를 가운데에 맞춰 보여 줍니다. **채우기**는 상자를 채우고 이미지를 잘라냅니다.

상자 필드를 하나라도 설정하면 프리셋 레이어가 **사용자 지정**으로 바뀝니다. 미리 보기에서 프리셋 레이어를 끌거나 크기를 바꿔도 마찬가지입니다. 높이가 화면 비율을 따르는 세로로 긴 이미지는 항상 프레임 안에 맞춰집니다. 1080×1920 동영상에서 너비 60%로 지정한 1:10 이미지는 192×1920으로 그려집니다. 그려지는 크기는 짝수 픽셀로 내림되며, 최소 2×2입니다.

### 시간 규칙
- 시간은 동영상 시작부터의 초로, 0~3,600입니다. 입력한 정밀도가 유지되며, 렌더링 시 동영상의 프레임 단위에 맞춰 배치되므로 레이어가 최대 한 프레임 일찍 또는 늦게 나타날 수 있습니다.
- <strong>끝(초)</strong>가 동영상 끝을 넘는 레이어는 동영상 끝에서 잘립니다.
- 동영상 끝 이후에 시작하는 레이어는 건너뛰며, 그 이미지는 다운로드하지 않습니다.
- 0.3초보다 짧은 레이어는 길이의 절반을 각 페이드에 씁니다.

패널은 입력하는 동안 브라우저가 읽은 길이를 기준으로 잘리거나 건너뛸 레이어를 경고합니다. 그 길이는 동영상 자체의 길이와 100분의 몇 초 차이가 날 수 있으므로, 최종 판단은 실행의 경고를 따릅니다.

## 출력 설정
| 설정 | 하는 일 |
| --- | --- |
| **출력 화면 비율** | **동영상과 동일**(기본값), `16:9`(1920×1080), `9:16`(1080×1920), `1:1`(1080×1080), `4:5`(1080×1350) 중 하나입니다. 출력 화면 비율을 지정하면 레이어 백분율은 그 새 프레임 기준입니다. |
| **동영상 맞춤** | 출력 화면 비율을 지정한 경우에만 쓰입니다. **채우기**(기본값)는 프레임을 채우고 동영상을 잘라냅니다. **전체 표시**는 동영상 전체를 보여 주고 여백을 둡니다. |
| **여백 색상** | **전체 표시**에서만 쓰입니다. 여백의 색입니다. 기본값은 검은색입니다. |

출력 화면 비율을 지정하지 않으면 결과는 동영상 고유의 표시 크기와 프레임 레이트를 유지합니다. 옆으로 저장된 휴대폰 클립은 똑바로 렌더링되고, 정사각형이 아닌 픽셀은 보정되며, 홀수 크기는 짝수로 내림되므로 1079×1919 원본은 1078×1918로 렌더링됩니다.

결과는 다운로드가 끝나기 전에 재생이 시작되는 H.264 MP4입니다. 기본 동영상의 첫 번째 오디오 트랙만 유지되며, 오디오가 없는 동영상은 무음으로 남습니다.

## 제한
- **레이어:** 실행당 1~20개. 이미지가 있는 레이어가 20개를 넘는 노드는 실행 전에 거부되며, **실행** 버튼이 그렇게 알려 줍니다. 레이어를 지워 20개로 되돌리세요. 남은 레이어는 번호를 그대로 유지합니다. 어떤 레이어도 조용히 빠지지 않으며, 비용도 청구되지 않습니다.
- **이미지:** PNG, JPEG, WebP이며, 파일당 최대 25MB, 합계 최대 100MB, 긴 변 최대 8,192픽셀, 합계 최대 4억 화소입니다. 카메라의 사진 방향 정보가 적용됩니다.
- **SVG는 거부됩니다.** 먼저 [이미지 오버레이](https://nodaro.ai/docs/nodes/image/image-overlay)로 SVG를 PNG로 바꾸세요.
- **애니메이션 이미지**는 애니메이션 WebP, APNG처럼 첫 프레임이 표시됩니다.
- **기본 입력은 동영상이어야 합니다.** 오디오 파일, 이미지, `.mp4`로 저장한 웹 페이지는 “기본 입력이 동영상이 아닙니다” 오류로 실패합니다.
- **렌더링 시간:** 렌더링은 10분이 지나면 중단됩니다.
- **API 요청 한도:** 사용자당 분당 최대 30회 요청.

## 경고
실행이 성공해도 경고를 보고할 수 있습니다. 설정 패널은 경고를 **마지막 실행** 한 줄에 보여 줍니다.

| 경고 | API 코드 | 의미 |
| --- | --- | --- |
| 잘림 | `clipped` | 레이어의 끝이 동영상 끝을 넘어서, 동영상 끝까지 표시되었습니다. |
| 건너뜀 | `skipped` | 레이어가 동영상 끝 이후에 시작해서, 그려지지 않았습니다. |
| 애니메이션 이미지 | `animated_first_frame` | 이미지가 애니메이션 WebP여서, 첫 프레임을 사용했습니다. |
| 오디오 재인코딩 | `audio_reencoded` | 동영상의 오디오를 그대로 MP4에 복사할 수 없어서, AAC로 다시 인코딩했습니다. |

모든 레이어가 동영상 끝 이후에 시작하면, 실행은 “모든 레이어가 동영상이 끝난 뒤에 시작합니다”라는 메시지와 함께 실패합니다. 레이어 이미지를 다운로드할 수 없을 때도 “레이어 3: 이미지를 가져올 수 없습니다”처럼 실행이 실패합니다.

## 크레딧
동영상 오버레이는 레이어 수나 동영상 길이와 관계없이 실행당 22크레딧이 듭니다. 실패한 실행에는 비용이 청구되지 않습니다. 셀프 호스팅한 Community Edition 설치에는 크레딧이 없으며, 노드는 API 키 없이 실행됩니다.

## 예시: 말하는 사람 위의 제품 카드
이미지 3개가 있는 9:16 셀카 동영상으로, 각 이미지는 화자가 언급하는 동안 표시됩니다.

| 레이어 | 이미지 | 시작(초) | 끝(초) | 배치 |
| --- | --- | --- | --- | --- |
| 1 | pricing-page.png | 1.2 | 2.6 | 카드 |
| 2 | dashboard.png | 3.0 | 4.4 | 카드 |
| 3 | logo.png | 0 | 끝까지 | 코너 배지, 오른쪽 위 |

1080×1920 동영상에서 각 카드의 상자는 (119, 307) 위치의 842×1152픽셀입니다. 화면 비율이 1:2인 스크린샷은 그 안에 가운데 맞춤으로 576×1152픽셀로 그려집니다.

같은 요청을 API의 `POST /v1/video-overlay`로 보내면 다음과 같습니다.

```json
{
"videoUrl": "https://example.com/selfie.mp4",
"layers": [
{ "imageUrl": "https://example.com/pricing-page.png", "start": 1.2, "end": 2.6, "preset": "card" },
{ "imageUrl": "https://example.com/dashboard.png", "start": 3.0, "end": 4.4, "preset": "card" },
{ "imageUrl": "https://example.com/logo.png", "start": 0, "preset": "corner-badge", "corner": "top-right" }
]
}
```

AI 어시스턴트는 `overlay_images` MCP 도구를 사용하며, 각 레이어에 `url`이나 `asset_id`를 지정합니다. 명령줄에서는 `nodaro media video-overlay`를 사용하세요.

## 팁
- **카드는 짧게, 따로따로 보여 주세요.** 카드는 1~2초 동안 보여 주고, 시간이 겹치지 않게 해서 한 번에 하나만 화면에 나오게 하세요.
- **오래 머무는 레이어에는 모서리를 쓰세요.** 오래 떠 있는 로고, 핸들, 가격은 화자에게서 떨어진 코너 배지나 사용자 지정 상자에 넣으세요.
- **로고에는 투명 PNG를 쓰세요.** 불투명한 JPEG는 사각형으로 놓입니다.
- **동영상 고유의 프레임을 유지하세요.** 원본과 다른 프레임이 필요할 때만 **출력 화면 비율**을 설정하세요.
- **먼저 자르세요.** 동영상 오버레이 전에 [동영상 자르기](https://nodaro.ai/docs/nodes/video/trim-video)로 기본 동영상을 짧게 만드세요.
- **자막은 나중에 넣으세요.** 결과를 [자막 추가](https://nodaro.ai/docs/nodes/video/add-captions)에 연결하세요. 레이어는 자막 아래에 놓입니다.
- **배지는 먼저 꾸미세요.** [이미지 오버레이](https://nodaro.ai/docs/nodes/image/image-overlay) 결과를 레이어 핸들에 연결하면 텍스트, QR 코드, 꾸민 배지를 동영상에 넣을 수 있습니다.

## 자주 묻는 질문

### 동영상 오버레이는 동영상 하나에 이미지를 몇 개까지 넣을 수 있나요?

실행당 최대 20개 레이어입니다. 캔버스의 노드에는 연결한 이미지용 레이어 핸들이 최대 12개 있습니다. 레이어 13~20은 API, MCP 또는 템플릿으로 설정한 이미지 URL에서 옵니다.

### 동영상 오버레이가 동영상의 오디오를 바꾸나요?

아니요. 기본 동영상의 오디오는 유지됩니다. 오디오가 AAC, MP3, AC-3, Opus이면 그대로 복사하고, 그렇지 않으면 AAC로 다시 인코딩하며, 실행은 이를 경고로 알려 줍니다.

### 카드가 화자의 얼굴을 가리는 이유는 무엇인가요?

카드 배치는 일부러 화면 가운데 위에 놓입니다. 말하는 사람 위로 제품 카드가 튀어나오게 하기 위해서입니다. 피사체를 가리면 안 되는 로고나 배지에는 코너 배지나 사용자 지정 상자를 사용하세요.

### 레이어에 어떤 이미지 형식을 쓸 수 있나요?

PNG, JPEG, WebP이며, 파일당 최대 25MB, 합계 최대 100MB입니다. SVG는 거부되므로 먼저 이미지 오버레이로 PNG로 바꾸세요. 애니메이션 이미지는 첫 프레임이 표시됩니다.

### 동영상 오버레이는 크레딧이 얼마나 드나요?

레이어 수나 동영상 길이와 관계없이 실행당 22크레딧입니다. AI 모델은 실행되지 않습니다. 셀프 호스팅한 Community Edition 설치에서는 크레딧이나 API 키 없이 실행됩니다.