# 파일 형식과 예제

댓글은 **TXT**, 정리한 시간표는 **호환 JSON**, 합방 이름은 **참가자 파일**을 사용합니다.

**JSON·TXT는 ttaem.com에 올리지 않고 사용할 수 있습니다.** 앱에서 여는 순서는 [요약과 JSON 가져오기](summary.md), d1·d2·point의 뜻은 [시간축 용어](timeline.md)에 있습니다.

## 평문 TXT

기존 댓글 평문은 TXT로 가져와 미리보기할 수 있습니다. JSON을 작성할 필요는 없습니다. 원문·시각·진단을 확인한 뒤 시간축에 불러옵니다.

## 시간축 JSON 가져오기

**댓글 가져오기 → 시간표 파일 열기 → 미리보기 → 시간축에 불러오기** 순서로 사용합니다. 파일을 고르기만 해서는 기존 자료가 바뀌지 않습니다.

아래 형식으로 시간표를 전달합니다. 요약 원본·컷 작업·영상 파일과는 다른 입력입니다.

```json
{
  "format": "chzzk.comment-timeline",
  "version": 1,
  "documents": [{
    "name": "가상 게임 목차",
    "aliases": [{"alias": "역할A", "streamer": "가상 방송인 A"}],
    "entries": [
      {"role": "chapter", "depth": 1, "startSec": 0, "endSec": 60, "title": "첫 게임"},
      {"startSec": 10, "title": "첫 만남 (w. 역할A)"},
      {"role": "highlight", "startSec": 20, "endSec": 25, "title": "결정적인 순간"}
    ]
  }]
}
```

**예상구간**은 `raw`에 `- 03:00 ~ 03:20 [H?] 검토할 장면`처럼 담으세요. 현재 `entries`의 `expected_highlight` 직접 지정은 지원하지 않습니다.

[시간축 JSON 예제 열기](../../examples/portable-timeline.json) · [예상구간 포함 예제](../../examples/summary-timeline.json)

:::details JSON 필드와 입력 제한

| 필드 | 의미·조건 |
|---|---|
| `documents` | 1–100개의 원문 문서. 서로 다른 문서의 부모·구간·별칭을 섞지 않음 |
| 문서 `name` | 선택한 시간표의 표시 이름, 최대 120자 |
| `raw` 또는 `entries` | 둘 중 하나. `raw`는 기존 댓글 문자열을 그대로 보존. `entries`는 시간과 종류를 항목별로 작성 |
| `aliases` | 선택적 문서별 가명 목록, 최대 100개. alias/streamer는 공백만으로 이루어지지 않은 80자 이하 문자열; 줄바꿈·대괄호·꺾쇠·슬래시 금지 |
| 항목 `startSec` | 0 이상의 안전한 정수, VOD 경과초 |
| `endSec` | 선택적 정수, 시작보다 뒤. 영상 길이와 항목 종류가 맞는지 미리보기에서 확인 |
| `title` | 줄바꿈 없는 1,000자 이하 문자열 |
| `role` | 생략하면 `point`; `chapter`, `memo`, `watch`, `highlight`, `collab_context`. 예상구간은 아래 현재 버전 제한 확인 |
| `depth` | chapter일 때 1–6; 바로 위 주제와 구간이 맞는지 확인 |
| 루트 `videoNo` | 선택 필드. 지정하면 현재 다시보기 번호와 같아야 함 |

입력은 250,000자 이하, 문서당 항목은 최대 5,000개입니다. `point`에는 `endSec`를 붙이지 않습니다. 구간은 `memo`나 `highlight`를 사용하세요.

원문 댓글이 있다면 `raw`에 그대로 담으세요. 항목별 `entries`에 넣은 제목 때문에 다른 시각이나 종류로 읽히면 `raw`로 바꿔 가져오세요. 채널 ID나 영상 동기화 정보는 이 시간표 파일에 포함하지 않습니다.

:::

## 참가자와 역할 이름 가져오기

참가자 이름으로 방송인을 찾고, 기준 영상과 방송 시각이 겹치는 다시보기를 불러옵니다. 실제 참여와 정확한 시각은 영상을 보고 확인하세요.

### 한 줄 입력

```text
가상 방송인 A, 탐정=가상 방송인 A, 기자=가상 방송인 B
```

쉼표로 나누고 `역할명=방송인`으로 별칭을 연결합니다. 같은 방송인은 한 명으로 묶습니다. 별칭이 여러 사람과 충돌하면 확인이 필요합니다.

:::details 이름 입력 제한

한 줄 2,000자, 이름 80자, 참가자 1–24명까지입니다. 입력은 현재 영상의 검색 보조 자료입니다. 댓글 안의 `별칭:`은 해당 댓글에만 적용하며, 입력과 충돌하면 자동 신원 선택을 멈춥니다.

:::

### 참가자 파일

```json
{
  "schema": "chzzk.participant-roster",
  "version": 1,
  "members": [
    {"streamer": "가상 방송인 A"},
    {"streamer": "가상 방송인 B"}
  ],
  "aliases": [
    {"alias": "탐정", "streamer": "가상 방송인 A"},
    {"alias": "기자", "streamer": "가상 방송인 B"}
  ]
}
```

`aliases`는 선택사항이며 선언 대상이 `members`에 있어야 합니다. 파일의 단일 이름에 쉼표·등호·줄바꿈·HTML을 넣지 않습니다. [예제 파일](../../examples/participant-roster.json)를 사용할 수 있습니다. 도구가 명시된 참가자 파일을 선택하면 참가자 자료로 적용합니다. [시간축 JSON](files.md)은 장면 미리보기 후 별도 채택하므로 두 파일의 적용 목적이 다릅니다.

### 기존 Syncher 합방 자료

이미 연결한 다시보기와 기준 시각을 전달하는 기존 합방 자료도 읽을 수 있습니다. 컷 작업 파일과는 다릅니다.

:::details Syncher 파일 조건

기존 `schemaVersion: 3` 자료도 읽습니다. 최소 `projectId` 문자열과 2–12명의 `people`이 필요합니다. 각 인물은 고유한 `id`, `name`과 `vod.url`을 가지며, `vod.url`은 `https://chzzk.naver.com/video/숫자`입니다. 현재 기준 VOD가 명단에 포함되어야 하고 중복 VOD는 거부합니다. `vod.wallAnchorSec`와 `vod.vodAnchorSec`가 유효하면 차이를 영상 0초의 벽시계 기준으로 사용합니다. `vod.verified: true`가 있어도 실제 같은 장면과 소리는 직접 확인하세요.

참가자 파일은 이름 검색에 필요한 최소 구조입니다. Syncher 자료는 이미 연결한 VOD와 기준 시각을 전달하는 기존 제품 자료입니다. 컷 작업 JSON과 자동 게시 형식으로 쓰지 않습니다.

:::

### 자동 선택과 보정

이름과 공개 메타데이터로 방송 시간대가 겹치는 다시보기 후보를 찾습니다. 표시 중인 명단의 처음 12명을 조회하고 **더보기**마다 다음 12명을 이어 불러옵니다. 12명은 표시 단위이며 위의 파일 입력 인원 제한과 다릅니다. 같은 검증 채널의 분할 VOD는 한 행에 시간순으로 표시합니다. 이름이 모호하면 직접 선택하고, 일부 조회·영상 미연결 상태를 목록에서 확인하세요. 비교 영상을 연 뒤 같은 장면이 조금 어긋나면 **시각 보정**으로 맞출 수 있습니다. 보정은 원본·비교 영상 조합별로 저장합니다. 문서 전체·수동 명단은 조회 범위이며 시각이 있는 합방 구간의 참석을 대신하지 않습니다. [이름 선택과 접근 조건](people.md#이름-확인과-공개-다시보기-조회)을 확인하세요.


시간표·합방·집계·컷을 함께 전달하려면 [링크로 공유하기](sharing.md)를 사용하세요. 댓글이 없는 다시보기에서도 공유 자료를 볼 수 있습니다.