youtube-dl의 DMCA 테이크다운 사태 이후, 비슷한 상황을 대비하기 위해 youtube-dl의 포크 프로젝트 youtube-dlc의 포크 프로젝트(...)인 yt-dlp를 추가했습니다.
설정에서 취향껏 골라서 사용하시면 되며 youtube-dl가 우선 지원됩니다.

API

공통사항

모든 요청은 POST 또는 GET만 받습니다. 그리고 응답은 JSON 형식입니다.
모든 요청엔 플러그인 이름 정보가 있어야 합니다. plugin 키에 담아서 보내면 됩니다. 만약 플러그인 이름 정보가 없으면 403 에러를 반환합니다.
요청을 처리하는 과정에서 예외가 발생하면 500 에러를 반환합니다. 이건 저한테 로그와 함께 알려주시면 됩니다.
모든 응답에는 errorCode 키가 있습니다. 코드의 의미는 아래 문단 참고

에러 코드 (errorCode)

0 - 성공. 문제없음
1 - 필수 요청 변수가 없음
2 - 잘못된 동영상 주소
3 - 인덱스 범위를 벗어남
4 - 키 값이 일치하지 않음
5 - 허용되지 않은 값이 있음
10 - 실패. 요청은 성공하였으나 실행 결과가 실패

Status 타입

상태를 나타냄

"READY" - 준비
"START" - 분석중
"DOWNLOADING" - 다운로드중
"ERROR" - 실패
"FINISHED" - 변환중
"STOP" - 중지
"COMPLETED" - 완료

/youtube-dl/api/info_dict

동영상 정보를 반환하는 API

Request

키	설명	필수	타입
`plugin`	플러그인 이름	O	String
`url`	동영상 주소	O	String

Response

키	설명	타입
`errorCode`	에러 코드	Integer
`info_dict`	동영상 정보	Object

동영상 정보(info_dict 키)에는 youtube-dl에서 생성한 info_dict 정보가 그대로 들어있습니다. 따라서 이 부분은 직접 주소를 넣어가며 반환되는 정보를 확인해보는 게 좋습니다.
간단한 예로 thumbnail 키엔 썸네일 주소, uploader 키엔 업로더 이름, title 키엔 동영상 제목, duration 키엔 동영상 길이 등이 들어 있습니다.
그리고 만약 주소가 플레이리스트라면 _type 키에 "playlist"라는 값이 들어 있습니다. 이때는 entries 키에 리스트가 들어있어 동영상들의 제목과 ID를 확인할 수 있습니다.

/youtube-dl/api/download

비디오 다운로드 준비를 요청하는 API

Request

키	설명	필수	타입
`plugin`	플러그인 이름	O	String
`key`	임의의 키. 이후 다운로드를 제어할 때 이 키가 필요함	O	String
`url`	동영상 주소	O	String
`filename`	파일명. 템플릿 규칙은 https://github.com/ytdl-org/youtube-dl/#output-template 참고. 미지정 시 사용자 설정	X	String
`save_path`	저장 폴더 경로. 미지정 시 사용자 설정	X	String
`format`	동영상 포맷. 포맷 지정은 https://github.com/ytdl-org/youtube-dl/#format-selection 참고. 미지정 시 최고 화질	X	String
`preferedformat`	변환할 비디오 포맷. 가능한 포맷은 https://ffmpeg.org/general.html#File-Formats 참고. 미지정 시 변환하지 않음	X	String
`preferredcodec`	추출할 오디오 코덱. 가능한 값은 `"best"`, `"mp3"`, `"aac"`, `"flac"`, `"m4a"`, `"opus"`, `"vorbis"`, `"wav"`. 미지정 시 추출하지 않음	X	String
`preferredquality`	추출한 오디오의 비트레이트. 0 ~ 9 사이의 VBR 퀄리티 값(0에 가까울수록 좋음) 혹은 특정 비트레이트 값. `preferredcodec` 키가 있을 때만 유효. 기본값: `192`	X	Integer
`dateafter`	지정한 날짜 이후에 업로드된 동영상만 다운로드. 미지정 시 모두 다운로드	X	String
`playlist`	플레이리스트를 다운로드할 때 범위나 순서 지정. 미지정 시 모두 순서대로 다운로드	X	String
`archive`	다운로드한 동영상의 ID를 기록할 파일 경로. 파일이 이미 있으면 이미 다운로드한 동영상은 다운로드 하지 않음. 미지정 시 기록하지 않음	X	String
`start`	다운로드 준비 후 바로 다운로드를 시작할지 여부. 기본값: `false`	X	Boolean
`cookiefile`	다운로드 시 필요한 쿠키 파일 경로	X	String
`headers`	다운로드 시 사용할 HTTP 헤더 정보	X	String

dateafter 키에 넣을 수 있는 날짜는 "YYYYMMDD" 또는 "(now|today)[+-][0-9](day|week|month|year)(s)?" 형식의 문자열입니다.
headers 키에 넣는 값은 json 형식의 문자열입니다.

playlist 키에 넣을 수 있는 값은 "1-3,7,10-13" 형식의 범위 또는 "reverse", "random"입니다.
범위를 넣으면 플레이리스트에서 선택한 것만 다운로드합니다.
"reverse"를 넣으면 전체 플레이리스트를 역순으로 다운로드합니다.
"random"을 넣으면 전체 플레이리스트를 랜덤 순서로 다운로드합니다.

Response

키	설명	타입
`errorCode`	에러 코드	Integer
`index`	동영상 인덱스. 이후 다운로드를 제어할 때 이 값이 필요함	Integer

/youtube-dl/api/thumbnail

썸네일 다운로드 준비를 요청하는 API

Request

키	설명	필수	타입
`plugin`	플러그인 이름	O	String
`key`	임의의 키. 이후 다운로드를 제어할 때 이 키가 필요함	O	String
`url`	동영상 주소	O	String
`filename`	파일명. 템플릿 규칙은 https://github.com/ytdl-org/youtube-dl/#output-template 참고. 미지정 시 사용자 설정	X	String
`save_path`	저장 폴더 경로. 미지정 시 사용자 설정	X	String
`all_thumbnails`	모든 썸네일 다운로드 여부. `false`는 대표 썸네일 하나만 다운로드. 기본값: `false`	X	Boolean
`dateafter`	지정한 날짜 이후에 업로드된 동영상만 다운로드. 미지정 시 모두 다운로드	X	String
`playlist`	플레이리스트를 다운로드할 때 범위나 순서 지정. 미지정 시 모두 순서대로 다운로드	X	String
`archive`	다운로드한 동영상의 ID를 기록할 파일 경로. 파일이 이미 있으면 이미 다운로드한 동영상은 다운로드 하지 않음. 미지정 시 기록하지 않음	X	String
`start`	다운로드 준비 후 바로 다운로드를 시작할지 여부. 기본값: `false`	X	Boolean
`cookiefile`	다운로드 시 필요한 쿠키 파일 경로	X	String
`headers`	다운로드 시 사용할 HTTP 헤더 정보	X	String

Response

키	설명	타입
`errorCode`	에러 코드	Integer
`index`	동영상 인덱스. 이후 다운로드를 제어할 때 이 값이 필요함	Integer

/youtube-dl/api/sub

자막 다운로드 준비를 요청하는 API

Request

키	설명	필수	타입
`plugin`	플러그인 이름	O	String
`key`	임의의 키. 이후 다운로드를 제어할 때 이 키가 필요함	O	String
`url`	동영상 주소	O	String
`filename`	파일명. 템플릿 규칙은 https://github.com/ytdl-org/youtube-dl/#output-template 참고. 미지정 시 사용자 설정	X	String
`save_path`	저장 폴더 경로. 미지정 시 사용자 설정	X	String
`all_subs`	모든 자막 다운로드 여부. 기본값: `false`	X	Boolean
`sub_lang`	자막 언어. 두 자리 국가 코드. 콤마(,)를 구분자로 여러 개 지정 가능. `all_subs` 키가 `false`일 때만 유효. 기본값: `"ko"`	X	String
`auto_sub`	자동생성 자막 다운로드 여부. 유튜브 전용. 기본값: `false`	X	Boolean
`dateafter`	지정한 날짜 이후에 업로드된 동영상만 다운로드. 미지정 시 모두 다운로드	X	String
`playlist`	플레이리스트를 다운로드할 때 범위나 순서 지정. 미지정 시 모두 순서대로 다운로드	X	String
`archive`	다운로드한 동영상의 ID를 기록할 파일 경로. 파일이 이미 있으면 이미 다운로드한 동영상은 다운로드 하지 않음. 미지정 시 기록하지 않음	X	String
`start`	다운로드 준비 후 바로 다운로드를 시작할지 여부. 기본값: `false`	X	Boolean
`cookiefile`	다운로드 시 필요한 쿠키 파일 경로	X	String
`headers`	다운로드 시 사용할 HTTP 헤더 정보	X	String

Response

키	설명	타입
`errorCode`	에러 코드	Integer
`index`	동영상 인덱스. 이후 다운로드를 제어할 때 이 값이 필요함	Integer

/youtube-dl/api/start

다운로드 시작을 요청하는 API

Request

키	설명	필수	타입
`plugin`	플러그인 이름	O	String
`index`	제어할 동영상의 인덱스	O	Integer
`key`	제어할 동영상에게 넘겨준 키. 이 값이 일치해야 요청이 실행됨	O	String

Response

키	설명	타입
`errorCode`	에러 코드	Integer
`status`	요청을 받았을 당시의 상태	Status

/youtube-dl/api/stop

다운로드 중지를 요청하는 API

Request

키	설명	필수	타입
`plugin`	플러그인 이름	O	String
`index`	제어할 동영상의 인덱스	O	Integer
`key`	제어할 동영상에게 넘겨준 키. 이 값이 일치해야 요청이 실행됨	O	String

Response

키	설명	타입
`errorCode`	에러 코드	Integer
`status`	요청을 받았을 당시의 상태	Status

/youtube-dl/api/status

현재 상태를 반환하는 API

Request

키	설명	필수	타입
`plugin`	플러그인 이름	O	String
`index`	제어할 동영상의 인덱스	O	Integer
`key`	제어할 동영상에게 넘겨준 키. 이 값이 일치해야 요청이 실행됨	O	String

Response

키	설명	타입
`errorCode`	에러 코드	Integer
`status`	요청을 받았을 당시의 상태	Status
`type`	다운로드 타입. `"video" "thumbnail" "subtitle"`	String
`start_time`	다운로드 시작 시간	String
`end_time`	다운로드 종료 시간	String
`temp_path`	임시 폴더 경로	String
`save_path`	저장 폴더 경로	String

start_time 키와 end_time 키에 들어있는 시간은 "YYYY-MM-DDThh:mm:ss" 형식의 문자열입니다.
물론 해당 정보가 없으면 null입니다.

Changelog

v0.1.2

유튜브 검색 속도 대폭 개선 (extract_flat 적용)
검색 결과 캐싱 추가 (5분 유지)
인피니티 스크롤 안정화 및 최적화
미니 플레이어 (스크롤 시 오른쪽 하단 고정) 추가
Artplayer 영상 비율 버그 수정 (16:9 aspect-ratio 적용)
UI 개선: 검색 후 초기 메시지 자동 숨김

v0.1.1

유지보수 업데이트

v0.1.0

최초 공개