참고: 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 자막 트랙의 유형입니다. 이 속성에 유효한 값은 다음과 같습니다.
|
snippet.language |
string 자막 트랙의 언어입니다. 속성 값은 BCP-47 언어 태그입니다. |
snippet.name |
string 자막 트랙의 이름입니다. 이름은 재생 중에 사용자에게 옵션으로 표시됩니다. 지원되는 최대 이름 길이는 150자(영문 기준)입니다. |
snippet.audioTrackType |
string 자막 트랙과 연결된 오디오 트랙의 유형입니다. 이 속성에 유효한 값은 다음과 같습니다.
|
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 자막 트랙의 상태입니다. 이 속성에 유효한 값은 다음과 같습니다.
|
snippet.failureReason |
string YouTube가 자막 트랙을 처리하지 못한 이유입니다. 이 속성은 state 속성의 값이 failed 인 경우에만 존재합니다.이 속성에 유효한 값은 다음과 같습니다.
|