# youtube-dl_sjva [SJVA](https://sjva.me/) 용 [youtube-dl](https://youtube-dl.org/) 플러그인입니다. SJVA에서 유튜브, 네이버TV 등 동영상 사이트 영상을 다운로드할 수 있습니다. ## 설치 SJVA에서 "시스템 → 플러그인 → 플러그인 수동 설치" 칸에 저장소 주소를 넣고 설치 버튼을 누르면 됩니다. `https://github.com/joyfuI/youtube-dl` ## 잡담 시놀로지 docker 환경에서 테스트했습니다. API를 제공합니다. 다른 플러그인에서 동영상 정보나 다운로드를 요청할 수 있습니다. 다른 플러그인이 멋대로 다운로드를 중지할 수 없도록 다운로드를 요청할 때 임의의 키를 넘겨받습니다. 중지 요청 시 키가 일치해야 요청이 실행됩니다. [youtube-dl](https://github.com/ytdl-org/youtube-dl)의 DMCA 테이크다운 사태 이후, 비슷한 상황을 대비하기 위해 youtube-dl의 포크 프로젝트 [youtube-dlc](https://github.com/blackjack4494/yt-dlc)의 포크 프로젝트(...)인 [yt-dlp](https://github.com/yt-dlp/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 | `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/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 | `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/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 v4.0.1 - 다운로드 요청 오류 수정 v4.0.0 - 최신 플러그인 구조로 변경 - download, thumbnail, sub API에 headers 키 추가 http 헤더 수정이 필요한 경우 활용할 수 있습니다. v3.1.1 - 디폴트 youtube_dl 패키지를 yt-dlp로 변경 v3.1.0 - yt-dlp일 때 작동 안하는 문제 수정 v3.0.1 - 다운로드 후 파일 이동이 안되던 문제 수정 v3.0.0 - SJVA3 대응 - SJVA에 flask_cors가 내장됨에 따라 항상 CORS 허용 v2.4.0 - API에 playlist 키 추가 플레이리스트 다운로드 시 범위나 순서를 지정할 수 있습니다. - 썸네일 다운로드 기능 추가 - thumbnail API 추가 - 자막 다운로드 기능 추가 - sub API 추가 - 설정에 경로 선택 버튼 추가 v2.3.1 - yt-dlp 패키지명 변경 대응 v2.3.0 - youtube-dlc를 yt-dlp로 변경 youtube-dlc가 2개월 넘게 커밋이 없어서 youtube-dlc의 포크 프로젝트인 yt-dlp로 변경했습니다. 기존에 youtube-dlc로 사용하던 분들은 yt-dlp로 변경됩니다. v2.2.0 - download API의 headers 키 제거 v2.1.2 - youtube-dlc 호환 문제 수정 v2.1.1 v2.1.0 - download API에 cookiefile, headers 키 추가 카카오TV 동영상 다운로드에 활용할 수 있습니다. 잘하면 로봇 체크 패스에도 사용이 가능한 듯 싶습니다. Thanks to [soju6jan](https://github.com/soju6jan) v2.0.0 - youtube-dlc 추가 사용할 youtube-dl 패키지를 선택할 수 있습니다. 설정 변경 후 재시작해야 적용됩니다. v1.7.0 - Python 3 지원 Python 2를 유지한 채로 Python 3 지원을 추가했습니다. - download API에 dateafter 추가 지정한 날짜 이후에 업로드된 동영상만 다운로드하는 옵션입니다. 플레이리스트 다운로드 시에 유용하게 사용할 수 있습니다. v1.6.11 - 목록 메뉴에 전체 중지 버튼 추가 v1.6.10 - CORS 허용 설정이 작동하지 않는 문제 수정 Thanks to [dbswnschl](https://github.com/dbswnschl) v1.6.9 - 일부 동영상 사이트에서 다운로드 실패하는 문제 수정 v1.6.8 - download API에서 filename 키가 적용되지 않는 문제 수정 v1.6.7 - 일부 상황에서 다운로드가 완료로 표시되지 않는 문제 수정 v1.6.6 v1.6.5 - info_dict API가 동작하지 않는 문제 수정 v1.6.4 - FFmpeg 경로 설정 추가 SJVA에 내장된 버전 말고 원하는 버전을 사용할 수 있습니다. - API에서 GET 요청 지원 이제 GET 요청으로도 API를 사용할 수 있습니다. v1.6.3 - 프록시 기능을 사용해도 국가차단 우회가 안 되는 문제 수정 v1.6.2 v1.6.1 v1.6.0 - API에 format_code를 format으로 변경 - API에 temp_path 삭제 v1.5.1 v1.5.0 - 프록시 설정 추가 - API에 archive 추가 download-archive 기능으로 다운로드한 동영상의 ID를 기록하여 이미 다운로드한 동영상은 다운로드 하지 않는 옵션입니다. - status API의 시간 형식 변경 (ISO 8601) v1.4.2 - --rm-cache-dir 옵션 추가 - 플러그인 최초 설치 시 작동 안 되는 문제 수정 v1.4.1 - CORS 허용 설정 추가 Thanks to [dbswnschl](https://github.com/dbswnschl) v1.4.0 - socketio 적용 목록 페이지에서 목록이 실시간으로 업데이트됩니다. v1.3.5 v1.3.4 - 플러그인 구조를 가이드에 맞춰 변경 플러그인 설정이 초기화됩니다. v1.3.3 - API 변경 v1.3.2 - 파일명에 경로 지정 시 이미 존재하는 경로면 에러가 발생하는 문제 수정 - celery 적용 v1.3.1 v1.3.0 - 후처리 기능 추가 이제 비디오 변환이나 오디오 추출이 가능합니다. 오디오 추출의 비트레이트는 192kbps로 설정되어 있습니다. v1.2.5 - 기본 파일명 설정 추가 - API에서 일부 키를 선택으로 변경 v1.2.4 - API Key 기능 추가 v1.2.3 - 저장 경로가 존재하지 않으면 생성하도록 개선 v1.2.2 - youtube-dl 패키지 업그레이드도 로그 찍히도록 수정 v1.2.1 v1.2.0 - API 추가 이제 다른 플러그인에서 동영상 정보 가져오기, 다운로드 요청이 가능합니다. 자세한 명세는 API 문단을 참고하세요. v1.1.1 - 플레이리스트 다운로드 중 국가차단 등의 이유로 다운로드 실패한 동영상이 있으면 건너뛰도록 개선 v1.1.0 - 화질 선택 기능 추가 - 잘못된 예외처리 수정 v1.0.2 v1.0.1 - 로그 좀 더 상세히 찍도록 수정 v1.0.0 - 바이너리 실행 방식에서 파이썬 임베딩 방식으로 변경 - SJVA 시작 시 자동으로 youtube-dl 업데이트 - 목록에서 진행률 표시 추가 v0.1.1 - 다운로드 실패 시 임시파일 삭제가 안 되는 문제 수정 v0.1.0 - 최초 공개