이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Captions

참고: 2024년 3월 13일에 YouTube는 captions.insert 및 captions.update API 엔드포인트의 sync 매개변수에 대한 지원 중단을 발표했습니다. 자막 자동 동기화는 YouTube 크리에이터 스튜디오에서 계속 사용할 수 있습니다. 자세한 내용은 API 업데이트 기록을 참고하세요.

caption 리소스는 YouTube 자막 트랙을 나타냅니다. 자막 트랙은 정확히 하나의 YouTube 동영상에 연결됩니다.

방법

API는 captions 리소스에 다음 메서드를 지원합니다.

list: 지정된 동영상에 연결된 자막 트랙 목록을 가져옵니다. API 응답은 실제 자막을 포함하지 않으며 captions.download 메서드는 자막 트랙을 검색하는 기능을 제공합니다. 지금 사용해 보세요.
insert: 자막 트랙을 업로드합니다.
업데이트: 자막 트랙을 업데이트합니다. 자막 트랙을 업데이트할 때 트랙의 초안 상태를 변경하거나 트랙의 새 자막 파일을 업로드하거나 이 두 가지 방법을 모두 사용할 수 있습니다.
삭제: 지정된 자막 트랙을 삭제합니다. 지금 사용해보기
다운로드: 자막 트랙을 다운로드합니다. 요청이 tlang 매개변수의 값을 지정하지 않는 한 요청이 tfmt 매개변수의 값을 원래 언어로 지정하지 않는 한 자막 트랙은 원래 형식으로 반환됩니다.

리소스 표현

다음 JSON 구조는 captions 리소스의 형식을 보여줍니다.

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

속성

다음 표는 이 리소스에 표시되는 속성을 정의합니다.

속성
`kind`	`string` API 리소스 유형을 식별합니다. 값은 `youtube#caption`입니다.
`etag`	`etag` 이 리소스의 Etag입니다.
`id`	`string` YouTube가 자막 트랙을 고유하게 식별하는 데 사용하는 ID입니다.
`snippet`	`object` `snippet` 객체에는 자막에 관한 기본 세부정보가 포함됩니다.
`snippet.videoId`	`string` YouTube가 자막 트랙에 연결된 동영상을 고유하게 식별하는 데 사용하는 ID입니다.
`snippet.lastUpdated`	`datetime` 자막 트랙이 마지막으로 업데이트된 날짜와 시간입니다. 값은 ISO 8601 형식으로 지정됩니다.
`snippet.trackKind`	`string` 자막 트랙의 유형입니다. 이 속성에 유효한 값은 다음과 같습니다. `ASR` - 자동 음성 인식을 사용하여 생성된 자막 트랙입니다. `forced` - 플레이어에서 다른 트랙을 선택하지 않으면 재생되는 자막 트랙입니다. 예를 들어 외계인이 외국어로 말하는 동영상의 경우 외국어에 대한 자막만 표시하는 강제 자막 트랙이 있을 수 있습니다. `standard` - 일반 자막 트랙입니다. 기본값입니다.
`snippet.language`	`string` 자막 트랙의 언어입니다. 속성 값은 BCP-47 언어 태그입니다.
`snippet.name`	`string` 자막 트랙의 이름입니다. 이름은 재생 중에 사용자에게 옵션으로 표시됩니다. 지원되는 최대 이름 길이는 150자(영문 기준)입니다.
`snippet.audioTrackType`	`string` 자막 트랙과 연결된 오디오 트랙의 유형입니다. 이 속성에 유효한 값은 다음과 같습니다. `commentary` – 자막 트랙은 디렉터리 해설과 같은 해설이 포함된 대체 오디오 트랙에 해당합니다. `descriptive` – 자막 트랙은 추가 설명 오디오가 포함된 대체 오디오 트랙에 해당합니다. `primary` - 자막 트랙은 동영상의 기본 오디오 트랙에 해당하며, 일반적으로 동영상과 연결되는 오디오 트랙입니다. `unknown` – 기본값입니다.
`snippet.isCC`	`boolean` 트랙에 청각장애인 및 난청 사용자를 위한 자막이 포함되어 있는지 나타냅니다. 기본값은 `false`입니다.
`snippet.isLarge`	`boolean` 자막 트랙에 시각 장애가 있는 사용자를 위해 큰 텍스트를 사용하는지 나타냅니다. 기본값은 `false`입니다.
`snippet.isEasyReader`	`boolean` 자막 트랙이 '읽기 쉬운 읽기'용으로 형식이 지정되었는지, 즉 언어 학습자에게 3학년 수준인지를 나타냅니다. 기본값은 `false`입니다.
`snippet.isDraft`	`boolean` 자막 트랙이 초안인지 여부를 나타냅니다. 값이 `true`이면 트랙이 공개적으로 표시되지 않습니다. 기본값은 `false`입니다.
`snippet.isAutoSynced`	`boolean` YouTube가 자막 트랙을 동영상의 오디오 트랙에 동기화했는지 나타냅니다. 자막 트랙이 업로드될 때 동기화를 명시적으로 요청한 경우 값은 `true`입니다. 예를 들어 `captions.insert` 또는 `captions.update` 메서드를 호출할 때 `sync` 매개변수를 `true`로 설정하여 YouTube에서 업로드된 트랙을 동영상에 동기화하도록 할 수 있습니다. 값이 `false`인 경우 YouTube는 업로드된 자막 트랙의 시간 코드를 사용하여 자막을 표시할 시점을 결정합니다.
`snippet.status`	`string` 자막 트랙의 상태입니다. 이 속성에 유효한 값은 다음과 같습니다. `failed` `serving` `syncing`
`snippet.failureReason`	`string` YouTube가 자막 트랙을 처리하지 못한 이유입니다. 이 속성은 `state` 속성의 값이 `failed`인 경우에만 존재합니다. 이 속성에 유효한 값은 다음과 같습니다. `processingFailed` – YouTube가 업로드된 자막 트랙을 처리하지 못했습니다. `unknownFormat` - 자막 트랙의 형식이 인식되지 않습니다. `unsupportedFormat` - 자막 트랙의 형식이 지원되지 않습니다.