Installation, operations, and mobile sharing guides for youtube-dl-nas
로그인된 대시보드에서 NAS로 영상, 오디오, 자막을 개별 다운로드하고 저장된 파일을 관리할 수 있습니다.
로그인 전 또는 대시보드 상단의 언어 선택기에서 English, 한국어, 简体中文, Polski를 선택할 수 있습니다. 처음 접속할 때 지원하는 브라우저 언어를 자동 감지하고, 지원하지 않는 언어는 영어로 표시하며, 직접 선택한 언어는 저장됩니다.
26.0906부터 데스크톱과 모바일 모두 다운로드, 컬렉션, AI 연결을
같은 탐색 메뉴에서 사용할 수 있습니다. 업그레이드할 때 기존 다운로드와
메타데이터 볼륨을 그대로 마운트하세요.
컬렉션 → URL 모으기에서 이름과 목적을 적고 직접 미디어 URL을 한 줄에 하나씩 입력합니다. 게시일 범위는 선택 사항이며, 기본 한도는 25개입니다. 후보 미리보기는 다운로드나 미디어 폴더 생성 없이 메타데이터, 날짜, 기존 파일과 대기 작업을 확인합니다. 범위를 벗어난 항목은 선택할 수 없습니다. 게시일을 확인할 수 없는 항목은 기본으로 선택되지 않으며, 날짜를 검증할 수 없다는 점을 받아들일 때만 직접 선택합니다.
추천된 기존 컬렉션이나 새 컬렉션을 선택한 뒤 한 번 승인하면 일괄 작업이 생성됩니다. 미리보기는 30분 동안 유효합니다. 이미 승인한 요청을 다시 보내도 같은 일괄 작업이 반환됩니다. 기존 파일은 복사하지 않고 연결하며, 같은 대기 작업도 다시 등록하지 않습니다.
컬렉션에는 목적, 게시일 기준, 고정된 저장 폴더, 항목 수, 용량과 일괄 진행 상태가 표시됩니다. 목록과 격자에서 파일을 미리 보거나 받을 수 있고, 상세 정보에서 기존 다운로드 관리 화면으로 이동할 수 있습니다. 앱 밖에서 지운 파일은 컬렉션에서 사라지는 대신 파일이 없다는 상태로 표시됩니다.
컬렉션 이름이나 목적을 바꿔도 실제 폴더는 바뀌지 않습니다. 컬렉션을 제거해도 파일과 폴더는 남고 이미 승인한 다운로드는 계속됩니다. 다운로드 화면에서 기록을 비우는 작업 역시 파일, 컬렉션, 소속 관계와 일괄 작업을 유지합니다.
AI 연결에서 연결 이름을 정하고 한 번만 표시되는 토큰을 복사한 다음, 사용할 클라이언트의 설정 안내를 따릅니다. 필요 없어진 연결은 개별적으로 해제할 수 있습니다. 웹 검색은 AI 클라이언트가 맡고, NAS는 전달받은 직접 URL을 검증하고 중복을 확인해 컬렉션과 대기열을 관리합니다. 자세한 설정과 접근 범위는 MCP 안내를 참고하세요.
호환성을 우선해야 하는 기기에서는 Compatible MP4 (H.264/AAC)를 선택하세요. 원본에 해당 코덱 조합이 없으면 다른 코덱으로 조용히 바꾸거나 트랜스코딩하지 않고 명확히 실패하며, 기존 Best의 의미는 바뀌지 않습니다.
요청이 정상적으로 큐에 들어가면 현재 기기에 선택한 프로필을 기억합니다. 새 기기이거나 저장값이 올바르지 않으면 Best로 돌아가며 URL을 자동 제출하지는 않습니다.
Options를 열면 미디어 옆에 JPG 썸네일을 저장하거나 이 기기의 PWA 모바일 공유 기본 프로필을 정하고, 제한된 소스에 사용할 Netscape 쿠키 파일을 관리할 수 있습니다. 항상 물어보기는 공유 URL을 바로 큐에 넣지 않고 입력창에 채워 출력 프로필을 확인하게 합니다.
쿠키는 계정 접근 권한을 포함할 수 있는 민감한 정보입니다. 접근 권한이 있는 사이트에서 내보낸 파일만 사용하세요. 앱 관리 파일은 1 MiB 제한과 형식 검사를 거쳐 메타데이터 볼륨에 소유자 전용 권한으로 저장되며 여기서 교체하거나 삭제할 수 있습니다. YTDLP_COOKIES_FILE로 외부 파일을 마운트한 경우에는 준비 상태만 표시하고 변경하지 않습니다.
재생목록이나 채널 URL을 입력하면 Playlist Guard가 범위 선택기를 표시합니다. 재생목록 파라미터가 붙은 개별 영상 URL은 현재 영상만이 기본값입니다. 순수 재생목록과 채널 URL은 처음 10개 또는 전체 항목을 명시적으로 골라야 큐에 넣을 수 있습니다. 완료된 각 항목은 파일과 기록에 별도 행으로 저장됩니다.
Current Activity에는 현재 제목, 채널, 썸네일, 진행률, 전송 속도와 남은 시간이 표시됩니다. Up next에서는 대기 중인 요청의 처리 순서, 요청 출처와 선택 화질을 확인할 수 있습니다.
요청이 활성화되면 Smart Preflight가 메타데이터와 NAS의 기존 파일을 확인하는 동안 3초 시작 유예가 함께 진행됩니다. 이 단계의 제거 버튼은 취소 기록을 만들지 않고 요청 자체를 되돌립니다. 확인과 유예가 모두 끝나면 별도 확인 없이 자동으로 전송을 시작하며, 메타데이터 응답이 느린 경우 3초를 추가로 기다리지 않습니다. 전송이 시작된 뒤에는 버튼이 정사각형 Stop 동작으로 바뀌고 호환되는 임시 데이터를 유지합니다.
같은 미디어 ID의 파일이 있으면 전송하지 않고 이미 NAS에 있음 결과에서 미리보기, 파일 받기와 상세 정보를 바로 열 수 있습니다. 웹소켓 갱신을 놓쳐도 결과는 잠시 유지됩니다. 메타데이터를 읽지 못한 경우에는 경고를 표시하되 실제 yt-dlp 다운로드 시도는 계속합니다.
큐는 데이터베이스 없이 영구 메타데이터 볼륨에 저장됩니다. 컨테이너가 재시작되면 중단된 활성 요청이 먼저 복원되고 나머지 요청이 기존 순서대로 이어집니다. 복원된 요청에는 Restored after restart가 표시됩니다. 호환되는 임시 파일은 yt-dlp가 이어받지만 정확한 바이트 구간 재개 지원은 원본 서비스에 따라 달라집니다.
같은 URL, 다운로드 프로필과 옵션은 공유 추적 파라미터를 제외하고 비교해 중복 등록을 막습니다. 메타데이터 추출 뒤에는 미디어 ID로 NAS의 기존 파일을 한 번 더 확인합니다. 같은 파일의 완료 신호가 반복되면 기존 기록과 최초 다운로드 날짜를 유지합니다. 완료 파일이 없는 실패 항목은 기존처럼 Retry할 수 있습니다.
데스크톱의 상세 영역은 라이브러리 개요로 시작합니다. 작은 화면과 모바일에서는 파일과 기록의 통계 버튼으로 같은 레이어를 열 수 있습니다. 현재 기록을 기준으로 저장 파일 수와 용량, 최근 7일 완료 수, 14일 활동 차트, 미디어 종류별 분포와 기록된 실패를 요약합니다. 마운트 파일은 저장 라이브러리 합계에는 포함하지만 다운로드 활동에서는 제외합니다. 미디어 종류나 실패 그룹을 선택하면 기존 기록 필터가 적용됩니다.
저장된 영상과 오디오는 다시 내려받지 않고 Preview로 재생할 수 있습니다. 저장한 썸네일 sidecar는 Grid 보기와 상세 정보에 사용됩니다. 실패 작업 재시도, 브라우저 다운로드, 기록만 삭제, 실제 파일과 연결된 썸네일 삭제 작업도 제공됩니다.
모바일 브라우저가 백그라운드에서 돌아오면 선택한 보기, 필터, 페이지와 상세 항목을 유지한 채 파일과 기록 및 현재 작업을 자동으로 갱신합니다.
SRT, VTT, ASS, SSA 자막 파일의 작업 메뉴에서 Subtitle QA를 선택합니다. 검증된 기준 원문을 붙여 넣고 필요하면 쉼표 또는 줄바꿈으로 키워드를 입력한 다음 Analyze를 누릅니다.
문자 정답률(CRR), 문자 오류율(CER), 단어 오류율(WER), 문자 대체·삭제·삽입 횟수와 키워드 보존 결과를 확인할 수 있습니다. 자막 파일과 입력한 기준 원문은 NAS 컨테이너 안에서만 처리됩니다. 새 컨테이너가 시작될 때 nlptutti를 설치하거나 최신 버전으로 갱신합니다.
/downfolder에 기존 파일이 있으면 자동으로 탐색합니다. 저장된 다운로드 기록이 없는 파일은 Mounted, No metadata로 표시됩니다. 미리보기, 브라우저 다운로드와 삭제는 가능하지만 원본 URL이나 화질 정보는 복원할 수 없습니다.
기록만 모두 지워도 실제 파일은 삭제되지 않습니다. 남겨진 파일은 다시 마운트 파일로 표시됩니다.
docker compose pull
docker compose up -d
latest와 26.1012 이미지는 linux/amd64, linux/arm64를 지원합니다.
기존 다운로드·메타데이터 마운트를 그대로 유지하세요. 수동 마이그레이션은
없으며 기존 파일명과 다운로드 날짜도 바뀌지 않습니다.
옵션 → 파일 이름에서 원래 제목, 채널 + 제목, 요청 날짜 + 제목을 고를 수 있습니다. 사용자 지정 제목은 최대 80자, UTF-8 기준 160바이트이며 경로 구분자나 제어 문자는 허용하지 않습니다. 미디어 ID와 확장자는 항상 유지합니다. 요청 날짜는 NAS의 시간대 기준이며 재시도해도 최초 날짜를 사용합니다. 기존 파일을 자동으로 바꾸거나, 이름만 바꿔 중복 검사를 우회하지 않습니다.
모바일에서는 검색을 바로 사용할 수 있고 필터를 펼쳐 정렬·상태·유형을 바꿉니다. 재생과 다운로드는 바로 누를 수 있으며 삭제는 더 보기 안에서 이름을 확인하고 진행합니다. 작업이 없을 때 현재 활동은 작게 표시하지만 이미 저장된 파일 안내는 계속 보여 줍니다.
실패한 항목의 상세 화면에서 쿠키 설정으로 이동하거나 다른 프로필로 재시도할 수 있습니다. 컬렉션·날짜 조건·파일명 옵션은 유지합니다. 안전한 진단 정보에는 앱/yt-dlp 버전, 상태, 실패 분류, 프로필, 저장 공간 상태만 포함합니다. URL·제목·파일 경로·쿠키·원본 로그는 포함하지 않습니다. 브라우저가 자동 복사를 막으면 표시된 텍스트를 선택해서 복사하세요.
휴대폰 공유 설정은 모바일 공유 설정을 참고하세요.