guohuiyuan/go-music-dl

⭐ 만약 이 프로젝트가 당신의 시간을 절약해 주고 있다면, Star를 눌러주세요. Star가 많아질수록 제작자는 이 도구가 실제로 사용되고 있음을 확인하고, 유효하지 않은 사이트 수정, 새로운 사이트 적응 및 버전 업데이트를 우선적으로 진행할 동력을 얻게 됩니다.

Go Music DL은 음악 검색 및 다운로드 도구로, Web 인터페이스 (Web Interface), TUI 터미널 (TUI Terminal), 그리고 데스크톱 애플리케이션 (Desktop Application) 세 가지 사용 모드를 지원합니다. 단일 곡 검색 및 다운로드 외에도 플레이리스트 검색 / 파싱 (Playlist Search / Parsing), 플레이리스트 카테고리 브라우징 (Playlist Category Browsing), 내 플레이리스트 (My Playlists), 앨범 검색 / 파싱 (Album Search / Parsing), 플레이리스트/앨범 전체 곡 확인 및 일괄 처리 기능을 지원합니다. 브라우저에서 미리 듣기를 하거나, 터미널에서 일괄 다운로드를 하거나, 네이티브 데스크톱 앱을 사용하여 최상의 경험을 누릴 수 있습니다.

가장 간단한 사용 방법은 다운로드 후 바로 사용하는 것입니다:

• Releases에서 다운로드
  music-dl-desktop-rust.exe

또는 music-dl-desktop-go.exe

• 압축 해제 후 더블 클릭하여 실행
• 네이티브 데스크톱 경험을 즐기세요!

모바일 기기 다운로드 안내: Releases 페이지에서 Android용 music-dl_arm64-v8a.apk (권장) / music-dl_x86_64.apk / music-dl.apk (분할 호환 패키지 없음)를 직접 다운로드할 수 있습니다.

Android APK에는 ffmpeg와 ffprobe가 내장되어 있어, 로컬 음악 탐지, 비 MP3 메타데이터 임베딩 및 비디오 렌더링을 위해 휴대폰에 별도로 FFmpeg를 설치할 필요가 없습니다. iOS의 경우 사용자가 직접 서명할 수 있도록 music-dl-ios-unsigned.ipa를 제공하며, 배포 환경에 인증서가 구성된 경우 서명된 music-dl-ios.ipa도 추가로 제공됩니다.

./music-dl web

Web 모드는 기본적으로 로그인 없이도 검색, 재생, 다운로드, 플레이리스트 / 앨범 브라우징 및 로컬 플레이리스트 사용 등의 일반 기능을 사용할 수 있습니다. 우측 상단의 설정 (Settings) 진입, 시스템 설정 저장, 플랫폼 Cookie 관리, QR 코드 스캔 로그인을 통한 Cookie 쓰기 등 시스템 구성 작업만 관리자 로그인이 필요합니다.

시스템 구성 로그인을 처음 트리거할 때 관리자 계정이 없다면, 터미널이 일회용 초기화 토큰을 출력합니다. 초기화 페이지를 열고 해당 토큰을 입력한 뒤, 사용자 이름과 최소 6자 이상의 비밀번호를 설정하면 관리자 계정을 생성할 수 있습니다. 이후 설정 또는 우측 상단의 로그인 버튼을 클릭하면 로그인 프로세스로 진입합니다. 세션 Cookie는 기본적으로 7일간 유지되며, 우측 상단 버튼은 상태에 따라 로그인 / 로그아웃으로 전환됩니다. 로그아웃 후에는 홈 화면으로 돌아가며 일반 기능은 계속 사용할 수 있습니다.

데스크톱 및 모바일 앱에 내장된 Web 서비스는 StartDesktop으로 시작되며, 오직 로컬 호스트 127.0.0.1만 리스닝(Listening)합니다. 또한 처음 실행 시 터미널 초기화 토큰을 보지 못해 앱에 진입하지 못하는 상황을 방지하기 위해 기본적으로 Web 관리자 로그인 프로세스를 비활성화합니다.

./music-dl -k "검색 키워드"

다중 모드 지원: Web 인터페이스, TUI 터미널, 데스크톱 애플리케이션
로컬 자체 제작 플레이리스트: 로컬 즐겨찾기 생성을 지원하여 원하는 곡을 언제든 즐겨찾기하고 관리할 수 있으며, 데이터가 영구적으로 보존됩니다.
플레이리스트 카테고리 브라우징: Web 단에서 플랫폼별 공식 카테고리를 확인할 수 있으며, 카테고리 진입 후 추천 플레이리스트를 브라우징하고 상세 정보를 열 수 있습니다.
내 플레이리스트: Web 단에서 로그인된 계정의 개인 플레이리스트 / 즐겨찾기 플레이리스트를 읽어올 수 있으며, 상세 정보 진입 및 일괄 처리를 지원합니다.
Cookie QR 코드 로그인: Web 설정 패널에서 QR 코드를 스캔하여 Cookie를 획득할 수 있으며, 성공 시 로컬 설정에 자동으로 저장됩니다. QQ Music(汽水音乐) QR 코드 로그인은 아직 연동되지 않아 입구가 임시로 숨겨져 있습니다.
로컬 음악 관리: Web 단에서 로컬 다운로드 디렉토리의 음악을 읽을 수 있으며, 업로드, 자체 제작 플레이리스트에 추가, 커버/가사 읽기 및 삭제를 지원합니다. 목록은 기본적으로 페이지 단위로 로딩되며 스캔 및 메타데이터를 캐싱하므로, 수천 곡의 로컬 음악도 빠르게 열 수 있습니다.
무손실 음악 지원: NetEase Cloud Music, QQ Music, Bilibili의 FLAC 무손실 음악 다운로드를 지원합니다.

• 다중 플랫폼 통합 검색, 단일 곡 / 플레이리스트 / 앨범 지원
• 미리 듣기, 가사, 커버 다운로드
  가사 이중 형식 지원: NetEase Cloud Music, QQ Music, Kugou는 원문 / 번역문 / 로마자 표기의 글자 단위 LRC 표시 및 카라오케 방식의 글자 단위 하이라이트를 지원합니다. 기타 채널은 원문 줄 단위 가사 표시를 유지합니다.
• Range 탐지: 크기 및 비트레이트(Bitrate) 표시
• QQ Music(汽水音乐) 등 암호화된 오디오 복호화
• 유료 리소스 필터링
  데스크톱 애플리케이션 특성: 네이티브 창, 자동 서비스 시작, 스마트 캐시 관리

Web: 단일 곡, 플레이리스트, 앨범 세 가지 검색 유형 전환을 지원하며, 플레이리스트 / 앨범 곡 목록을 직접 확인할 수 있습니다.
링크 파싱: 플레이리스트 링크 또는 앨범 링크를 직접 붙여넣으면 출처를 자동으로 인식하여 상세 페이지로 진입합니다.
플레이리스트 카테고리: Web 단에서 "플레이리스트 카테고리" 입구를 제공하여, 서로 다른 플랫폼 간에 카테고리 출처를 전환하고 카테고리별로 플레이리스트를 브라우징할 수 있습니다.
내 플레이리스트: Web 단에서 "내 플레이리스트" 입구를 제공하여, 로그인 후 개인적으로 생성, 즐겨찾기 또는 좋아요를 누른 플레이리스트를 볼 수 있습니다.
TUI: 입력 인터페이스에서 단일 곡 / 플레이리스트 / 앨범 간 전환을 지원하여, 플레이리스트/앨범 전체 처리에 적합합니다.
상세 페이지 이동: Web 곡 목록에서 곡으로부터 가수 검색 결과 또는 해당 앨범 페이지로 이동하는 것을 지원합니다.
채널 동기화: music-lib와 동기화되었습니다.

Migu, Jamendo, JOOX, QQ, Qishui 등의 플레이리스트 / 앨범 함수를 지원하며, JOOX 플레이리스트는 OpenJOOX 인터페이스와 웹 데이터 백업(fallback)을 지원합니다.

웹(Web) 홈 페이지의 플레이리스트 입구 옆에 **플레이리스트 분류 (Playlist Category)**와 **내 플레이리스트 (My Playlist)**가 제공됩니다:

플레이리스트 분류: NetEase Cloud Music, QQ, Kugou, Kuwo, Migu, QQ, JOOX, Apple Music을 지원합니다. 진입 후 플랫폼 태그를 전환하여 분류를 선택하고 해당 분류 아래의 플레이리스트를 확인할 수 있습니다. 내 플레이리스트: NetEase Cloud Music, QQ, Kugou, Qishui를 지원합니다. 먼저 웹 우측 상단의 "설정 (Settings)"에서 해당 플랫폼의 쿠키(Cookie)를 구성해야 합니다. QQ는 "내가 좋아하는 곡"과 즐겨찾기 플레이리스트를 지원하며, Qishui는 "좋아하는 음악"과 플레이리스트 가져오기를 지원하며, 모두 사이트 내에서 곡 목록을 파싱할 수 있습니다. 상세 정보 및 가져오기: 분류 플레이리스트와 내 플레이리스트 모두 상세 페이지로 진입할 수 있으며, 곡 목록은 재생, 다운로드, 일괄 작업(batch operations)을 지원하고 로컬 자작 플레이리스트로 가져올 수도 있습니다.

웹 우측 상단의 "설정"에서 각 플랫폼의 쿠키를 관리할 수 있습니다. QR 코드 로그인을 지원하는 플랫폼은 쿠키 입력창 오른쪽에 QR 스캔 (Scan QR) 버튼이 표시됩니다:

지원 플랫폼: NetEase Cloud Music, QQ Music, Kugou Music, Bilibili. 사용 방식: 해당 플랫폼의 "QR 스캔"을 클릭하고 공식 앱으로 QR 코드를 스캔하여 로그인을 확인합니다. 로그인에 성공하면 쿠키가 자동으로 입력창에 작성되고 로컬에 저장됩니다. Qishui Music: 새로운 버전의 공식 PC 패스포트(passport) QR 스캔 프로세스는 동적 a_bogus / msToken 리스크 제어 서명(risk control signature)에 의존하는데, 현재 연동되지 않아 웹 단에서는 QR 스캔 입구가 임시로 숨겨져 있습니다. Qishui 개인 플레이리스트나 다운로드 기능이 필요한 경우 먼저 수동으로 쿠키를 구성해야 합니다. 용도: 쿠키는 더 완전한 검색 / 다운로드 기능을 얻거나, "내 플레이리스트"를 읽고, 로그인 상태가 필요한 일부 고음질 데이터 또는 개인 데이터에 접근하는 데 사용됩니다. 저장 위치: 쿠키는 로컬 데이터 디렉토리에 저장되며 제3자 서비스로 업로드되지 않습니다. 쿠키가 포함된 설정 파일을 공개적으로 공유하지 마십시오.

웹 단은 "내 자작 플레이리스트" 옆에 로컬 다운로드 디렉토리의 오디오 파일을 관리하기 위한 로컬 음악 (Local Music) 입구를 제공합니다. 다운로드 디렉토리는 웹 우측 상단 "설정"의 "로컬 다운로드 디렉토리"에서 지정하며, 기본값은 data/downloads입니다. Android 단에서는 시스템 음악 앱이 인식하기 쉽도록 로컬 다운로드 디렉토리를 /sdcard/Music으로 설정하는 것을 권장합니다.

설정의 **음악 파일명 템플릿 (Music Filename Template)**은 {name}, {artist}, {album}, {source}, {id}, {ext}를 지원합니다. {ext}를 작성하지 않으면 확장자가 자동으로 추가됩니다. 템플릿의 / 또는 \는 상대 하위 디렉토리를 생성할 수 있습니다. 예를 들어 로컬 다운로드 디렉토리가 /app/data이고 템플릿이 {artist}/{album}/{name} - {artist}.{ext}인 경우, /app/data/가수/앨범/곡명 - 가수.flac과 같은 경로로 저장됩니다. 곡 메타데이터 자체에 포함된 슬래시(/)는 안전하게 _로 대체되며, .., . 등 경로 트래버설(path traversal) 구간은 무시됩니다.

자동 읽기: 로컬 음악 목록을 열면 다운로드 디렉토리를 스캔하여 일반 곡 목록과 동일한 데이터 구조를 반환하며, 출처는 local로 표시됩니다. 지원 형식: mp3, flac, m4a, ogg, wav, wma, aac. 음악 업로드: 팝업창에서 오디오 파일을 업로드할 수 있으며, 파일은 다운로드 디렉토리에 저장됩니다. 파일명이 충돌할 경우 자동으로 일련번호가 추가됩니다. 정보 보완: 오디오 파일 내의 제목, 가수, 앨범, 재생 시간, 커버 및 가사를 우선적으로 읽습니다. 누락된 경우 파일명이나 Unknown 등의 백업 정보를 사용합니다. 소요 시간 탐지: 재생 시간, 비트레이트(bitrate), 제목, 가수, 앨범 등 누락된 정보는 최대한 ffprobe를 통해 탐지하여 보완합니다. ffprobe가 설치되지 않은 경우에도 표시 및 추가는 가능하지만 일부 정보가 비어 있을 수 있습니다. 커버 및 가사: 커버는 오디오 내장 이미지를 우선적으로 읽고, 없는 경우 동일 디렉토리의 동일한 이름의 이미지(.jpg, .jpeg, .png, .webp, .bmp, .gif)를 찾습니다. 가사는 오디오 내장 가사를 우선적으로 읽고, 없는 경우 동일 디렉토리의 동일한 이름의 가사 파일(.lrc, .txt, .lyric)을 찾습니다. 목록 커버 표시: 로컬 음악 목록은 내장 커버의 /local_music/cover 주소를 직접 반환합니다. 내장 커버가 없는 경우에만 동일한 이름의 이미지를 백업으로 사용합니다. 검색 소스로 활용: 로컬 음악은 1순위 검색 소스인 local로 업그레이드되었으며, 소스 선택 그리드에 나타납니다 (기본값은 체크 해제). 체크하면 단일 곡 검색에서 키워드에 따라 일치하는 로컬 곡을 온라인 결과와 함께 반환합니다. 플레이리스트 검색으로 전환하고 local을 체크하면...

때, 이름 / 설명 / 생성자(Creator)에 따라 직접 만든 플레이리스트와 가져온 플레이리스트를 검색할 수 있습니다. 검색은 내장된 SQLite 인덱스 테이블에 의해 구동되어, 수천 곡의 로컬 음악도 빠르게 찾아낼 수 있습니다. 플레이리스트에 추가: 로컬 음악 팝업에서 대상 사용자 지정 플레이리스트를 선택하면 로컬 곡을 해당 플레이리스트에 추가할 수 있습니다. 일괄 즐겨찾기 (로컬 음악 페이지에서 여러 곡을 선택한 후 한 번에 대상 플레이리스트에 추가)도 지원합니다. 외부에서 가져온 플레이리스트나 앨범에는 로컬 음악을 직접 추가할 수 없습니다. 삭제: 로컬 음악 목록, 단일 곡 검색 결과의 로컬 곡, 그리고 로컬 플레이리스트 검색 결과 모두 삭제를 지원합니다. 로컬 곡은 하드 삭제 (Hard Delete) 방식으로 처리됩니다 (다운로드 디렉토리의 실제 파일을 제거하고 인덱스를 삭제함). 삭제 전에는 2차 확인 과정을 거칩니다. 삭제된 곡은 더 이상 검색 결과에 나타나지 않습니다. 플레이리스트 내 무효화 및 소스 교체: 즐겨찾기 된 로컬 곡을 삭제하면, 사용자 지정 플레이리스트 내의 해당 항목은 유지되되 무효화된 상태로 표시됩니다. 플레이리스트 상세 페이지에서 이를 온라인 음원으로 소스 교체 (Replace Source) 하여 다시 재생할 수 있습니다. 다른 소스와 동일한 구성: 로컬 곡 카드는 다른 소스의 카드와 기본적으로 동일하며, 다만 (이미 로컬에 있는 파일에는 의미가 없으므로) "로컬 디렉토리에 저장" 버튼만 제거됩니다. 재생, 즐겨찾기, 가사, 커버, 브라우저 다운로드, (플레이리스트 내) 소스 교체 등의 작업은 그대로 유지됩니다.

백엔드 캐시와 프런트엔드 페이지네이션을 결합하여 중복된 디스크 스캔 / ffprobe 및 태그(tag) 분석 오버헤드를 줄였습니다:

목록 페이지네이션 로딩: 로컬 음악 페이지는 "Web 페이지당 항목 수" 설정에 따라 페이지네이션을 수행하며, PgUp / PgDn을 통한 빠른 페이지 이동과 URL ?page= 상태 유지를 지원하여 수천 개의 항목을 한 번에 렌더링하는 것을 방지합니다. 스캔 스냅샷 캐시: GET /api/local_music 결과는 10초 동안 캐시됩니다. TTL(Time To Live) 내에 반복적으로 접근하면 재스캔 없이 스냅샷을 즉시 반환합니다. 백그라운드 비동기 갱신: 캐시가 만료되면 즉시 이전 결과를 반환하고 백그라운드에서 비동기 재스캔을 시작합니다. 페이지 상단에는 "백그라운드에서 로컬 음악 목록을 갱신 중입니다. 현재는 마지막 스캔 결과를 표시합니다"라는 메시지가 표시됩니다. 메타데이터 캐시: 각 곡의 제목 / 가수 / 앨범 / 커버 / 가사 / 재생 시간 / 비트레이트(Bitrate)는 경로 + 파일 크기 + 수정 시간으로 인덱싱됩니다. 인덱스가 일치하면 ffprobe 및 태그 분석을 건너뛰므로, 파일이 변경되지 않았다면 오버헤드가 거의 제로에 가깝습니다. 무효화 트리거: 로컬 음악을 업로드하거나 삭제하면 즉시 스냅샷 캐시가 무효화되며, 다음 요청 시 재스캔을 수행합니다. 강제 갱신: API 호출 시 ?refresh=1을 전달하면 캐시를 우회하여 전체 디렉토리를 재스캔할 수 있습니다. 검색 인덱스 테이블: 시작 시 data/settings.db에 비동기적으로 로컬 음악 인덱스 테이블을 생성합니다 (다운로드 디렉토리 인덱스: 스캔 시 파일에 따라 upsert 수행, 파일이 사라지면 해당 행 삭제). 이를 통해 "로컬 음악을 검색 소스로 사용"할 때 키워드 검색 시 매번 재스캔하거나 ffprobe를 실행할 필요가 없습니다. 검색 시에는 여전히 일치하는 결과에 대해 존재 여부를 검증하므로, 삭제되거나 이동된 파일은 결과에 나타나지 않습니다. Android 읽기 수정: Android 단에서 READ_MEDIA_AUDIO / READ_EXTERNAL_STORAGE 권한을 동적으로 요청하여, /sdcard/Music 하위의 로컬 음악을 읽지 못하던 문제를 수정했습니다.

Web 단 "설정"에 다운로드 시 메타데이터(커버/가사) 내장 스위치가 추가되었습니다:

기본값 꺼짐 (권장): 스트리밍 다운로드 방식을 사용하여 속도가 더 빠르며, Range를 통한 끊김 없는 다운로드 및 드래그 재생을 지원합니다. 켜짐: 다운로드 시 커버와 가사를 오디오 파일에 쓰려고 시도합니다 (embed).

⚠️ 메타데이터 내장은 FFmpeg에 의존합니다. FFmpeg가 설치되어 있지 않으면 내장 과정을 자동으로 건너뛰고 원본 오디오를 반환합니다.

FFmpeg 사용 가능 여부를 먼저 확인할 수 있습니다:

ffmpeg -version

일반적인 설치 방법:

• Windows:
  winget install Gyan.FFmpeg

• macOS:
  brew install ffmpeg

• Ubuntu/Debian:
  sudo apt install ffmpeg

ffprobe는 FFmpeg 도구 모음에 속하며 주로 로컬 음악의 재생 시간, 비트레이트 및 태그 탐지에 사용됩니다. ffmpeg는 주로 MP3가 아닌 오디오의 커버/가사 메타데이터를 쓰는 데 사용됩니다. 이들이 없어도 프로그램 실행이나 로컬 음악 목록 로딩에는 지장이 없으며, 관련 강화 기능만 하향 조정(downgrade)됩니다.

Docker 이미지: Dockerfile에는 Alpine의 ffmpeg 패키지가 설치되어 있으며, 빌드 시 ffmpeg와 ffprobe가 모두 사용 가능한지 확인합니다. Docker / Compose 배포 시에는 일반적으로 추가 설치가 필요 없습니다. GitHub Release의 Android APK: release.yml은 APK 빌드 후 Android arm / arm64 / x86 / x86_64용 ffmpeg와 ffprobe를 다운로드하여 APK의 assets/ffmpeg/<abi>/에 넣은 뒤 다시 zipalign을 수행합니다.

그리고 서명합니다. Android 앱이 시작된 후 자동으로 애플리케이션 전용 디렉터리에 압축 해제되며, 이러한 내장 바이너리 경로가 구성됩니다. GitHub Release의 CLI / 데스크톱 / iOS 패키지: 여전히 ffmpeg/ffprobe를 내장하지 않으며, CI 빌드 환경에 설치할 것을 요구하지 않습니다. 로컬 음악 감지 또는 비(非) MP3 메타데이터 내장 기능이 필요한 경우, 실행하는 장치에서 위 명령을 따라 직접 FFmpeg을 설치해야 합니다. Linux deb/rpm/AppImage: 여전히 외부 시스템 도구로 처리하며, 하드 의존성을 강제하지 않아 다양한 배포판에서 FFmpeg 패키지 소스 차이로 인한 설치 실패를 방지합니다.

블루투스 곡 전환 및 미디어 버튼: Android 앱이 블루투스로 차량용 장치에 연결되어 재생할 때, 스티어링 휠 버튼(이전 곡 / 다음 곡 / 일시 정지)을 지원하며, 시스템 미디어 세션(AVRCP)뿐만 아니라 차량용 장치가 웹 페이지를 통해 전송하는 미디어 버튼(MediaTrackNext / MediaTrackPrevious / MediaPlayPause)에도 대체 처리를 합니다. 전면 재생 시에 유효합니다. 웹 공백 키 재생/일시 정지: 웹 버전에서 스페이스바 단축키가 추가되어 재생/일시 정지를 전환할 수 있습니다. 입력 필드나 팝업이 열려 있을 때는 트리거되지 않아 오작동을 방지합니다. 로컬 음악의 검색 소스화: 로컬 음악은 일급 검색 소스(local, 기본적으로 체크 해제됨)가 되었습니다. 단일 곡 검색 시 로컬 결과와 온라인 결과를 함께 반환할 수 있으며, 플레이리스트 검색 시에는 로컬에서 생성/가져온 플레이리스트를 검색할 수 있습니다. 내장 SQLite 인덱스 테이블에 의해 구동되므로 몇천 곡의 로컬 음악도 빠르게 검색됩니다. 로컬 노래 카드는 다른 소스와 동일하며, '로컬 디렉터리에 저장' 버튼만 제거되었습니다. 일괄 컬렉션 강화: 일괄 작업 모드에서는 여러 출처의 원하는 노래를 체크하고 '일괄 컬렉션'을 눌러 목표 자작 플레이리스트에 한 번에 추가할 수 있습니다. 로컬 음악 페이지에서도 여러 곡을 선택하여 한 번에 컬렉션 할 수 있습니다. 로컬 음악 삭제 강화: 단일 곡 검색 결과 및 로컬 플레이리스트 검색 결과 내의 로컬 콘텐츠는 모두 삭제할 수 있습니다. 로컬 노래는 하드 삭제(파일 제거 + 인덱스 제거)가 되며, 로컬 노래를 컬렉션한 후 해당 노래를 삭제하면 자작 플레이리스트의 대응 항목은 유지되지만 비활성화된 상태로 표시되며, 플레이리스트 상세 페이지에서 소스를 온라인 음원으로 변경하여 재생을 복구할 수 있습니다. 웹 이미지 / 가사 다운로드 방식 변경: 노래 커버와 가사의 다운로드 버튼이 이제 브라우저를 통해 직접 다운로드되며, 더 이상 서버 로컬 다운로드 디렉터리에 쓰이지 않습니다. TUI 내장 미리 듣기: TUI 단일 곡 목록에서 p로 재생, s로 정지할 수 있으며, 시스템 ffplay 기반의 백그라운드 재생을 지원하고 종료 시 자동으로 멈춥니다. 웹 아키텍처 전면 재구성: 프론트엔드 코드가 완전히 모듈화(독립적인 JS / CSS / HTML 템플릿 분리)되었고, 백엔드 라우팅은 비즈니스 영역별로 분할(음악 검색, 플레이리스트 관리, 비디오 생성)되어 코드 유지보수성이 크게 향상되었습니다. 자작 플레이리스트 기능 추가: 웹 버전에서 로컬 컬렉션이 지원되어 사용자가 자유롭게 플레이리스트를 생성하고 편집하여 여러 플랫폼의 노래를 모아 컬렉션할 수 있습니다. 플레이리스트 분류 및 나의 플레이리스트 추가: 웹 버전에서 공식 분류 브라우징을 지원하며, 네이버(网易云), QQ, KuGou, Qisui 계정 아래의 개인 플레이리스트 / 컬렉션 플레이리스트를 읽어오는 것도 지원합니다. Cookie 스캔 코드 로그인 추가: 설정 패널에서 네이버(网易云), QQ, KuGou, Bilibili 스캔 코드를 통한 로그인이 지원되며, 성공하면 쿠키가 자동으로 저장됩니다. Qisui 음악의 신규 버전 스캔 코드 로그인은 동적 a_bogus / msToken 풍제 서명 문제로 인해 진입점이 임시적으로 숨겨졌습니다. 로컬 음악 기능 추가: 웹 버전에서 로컬 다운로드 디렉터리 읽기, 오디오 업로드, 메타 정보 자동 보완, 동일 이름의 커버/가사 읽기가 지원되며, 자작 플레이리스트에 추가할 수 있습니다. 로컬 음악 성능 최적화: 로컬 음악 목록이 페이지네이션 로딩, 스캔 스냅샷 및 메타데이터 캐싱을 지원하며, 만료 후 백그라운드 비동기 새로고침은 요청을 차단하지 않습니다. 업로드 / 삭제 시 자동으로 캐시를 무효화합니다. Android 버전에서는 READ_MEDIA_AUDIO 권한 신청이 /sdcard/Music 읽기로 수정되었습니다. Android APK에 FFmpeg / ffprobe 내장: GitHub Actions로 Android APK를 빌드할 때 4개 ABI의 ffmpeg / ffprobe를 다운로드하여 APK에 주입하고, 앱 시작 시 내장 바이너리 경로가 자동으로 구성됩니다. 로컬 음악 커버 수정: 로컬 음악 목록 스캔 시 오디오 내장 커버를 읽고 /local_music/cover를 반환합니다.

주소를 수정하여 동일한 이름의 이미지 커버만 표시되던 문제와 내장 커버가 목록에서 비어 있던 문제를 해결했습니다. Web 자동 음원 교체 (Web Auto-Source Switching) 최적화: 시스템 설정에 "무효 음원 자동 선택 및 일괄 교체" 스위치가 추가되었으며, 기본적으로 활성화되어 있습니다. 음악 목록에서 무효 음원이 감지되면 자동으로 선택하여 일괄 교체하며, 교체가 완료된 곡은 중복 교체를 방지하기 위해 선택 해제됩니다. 가사 정밀 동기화 (LRC) 강화: Web 홈 페이지, 곡 상세 페이지 및 비디오 렌더링에서 NetEase Cloud Music / QQ Music / Kugou의 원문, 번역문, 로마자 표기逐字 가사(word-by-word lyrics)를 통합 지원합니다. 그 외 채널은 기존처럼 원문 행 단위 가사를 사용합니다.

• Web 재생 버튼은 재생/정지 전환을 지원하며, 하단에 글로벌 재생 및 볼륨 제어 바가 추가되었습니다.
• Web 단일 곡은 "음원 교체"를 지원하며, 유사도 우선, 재생 시간 근접성, 재생 가능 여부 검증을 거칩니다.
• 음원 교체 시 soda 및 fivesing은 자동으로 제외됩니다.
• Web 설정에서 "무효 음원 자동 선택 및 일괄 교체"를 켜거나 끌 수 있습니다. 기본값은 활성화이며, 무효 음원 감지 시 현재 무효 항목에 대해서만 한 번 자동으로 처리하고, 교체 성공 후에는 선택 상태를 유지하지 않습니다.
• TUI에 r 키를 통한 일괄 음원 교체 기능이 추가되었으며, 교체 진행 상황이 표시됩니다.
• Web과 TUI 모두에서 "데일리 플레이리스트 추천"을 볼 수 있습니다.
• 동기화
  music-lib

플레이리스트 / 앨범 채널 함수를 보완하여 Migu, Jamendo, JOOX, QQ Music 등의 플레이리스트 검색, 상세 정보 및 링크 파싱 매핑을 완성했습니다. - Web 단에서 일괄 작업 지원: 전체 선택, 무효 항목 선택, 일괄 다운로드, 일괄 음원 교체.

데스크톱 애플리케이션은 브라우저를 열 필요 없이 사용할 수 있는 네이티브 윈도우 경험을 제공합니다.

• 🖥️ 네이티브 데스크톱 윈도우, 브라우저 불필요
• 🚀 내장 Web 서버 자동 실행
• 🎵 완전한 Web 인터페이스 기능
• 📦 단일 파일 배포, 무설치(Portable) 방식
• 🖼️ 사용자 정의 윈도우 아이콘
• 🔒 포트 충돌 방지를 위해 희귀 포트(37777) 사용

본 프로젝트는 다양한 Docker 배포 방식을 제공합니다. 현재 기본적으로 ./data 디렉토리를 컨테이너 내부의 /home/appuser/data에 마운트하며, 다운로드 파일, 설정 및 즐겨찾기 데이터는 모두 해당 디렉토리에 영구 저장(Persistence)됩니다.

주의: 호스트에서 다운로드 및 설정 데이터에 직접 접근하기 쉽도록, 처음 실행하기 전에 반드시 data 디렉토리를 생성해야 합니다 (예: mkdir -p data && chmod 777 data).

프로젝트에는 docker-compose.yml 파일이 포함되어 있어, 로컬에서 빌드할 필요 없이 클라우드의 프리컴파일된 이미지를 직접 가져올 수 있습니다:

# 최신 이미지 가져오기
docker compose pull
# 백그라운드에서 서비스 시작
...

브라우저에서 http://localhost:8080으로 접속하세요.

설명:

• guohuiyuan/go-music-dl:latest 이미지를 자동으로 가져옵니다. 백그라운드 실행 및 자동 재시작을 지원합니다.
• 데이터 영구 저장을 위해 기본적으로 ./data 로컬 디렉토리를 사용하므로 직접 확인 및 백업이 용이합니다.
• 시간대를 Asia/Shanghai로 설정합니다.
• 보안 향상을 위해 non-root 사용자(uid=1000)로 실행됩니다.

소스 코드를 수정하여 로컬에서 Docker를 통해 다시 빌드하고 효과를 테스트하고 싶다면 docker-compose.dev.yml을 사용하세요:

# 로컬에서 Dockerfile을 사용하여 강제로 빌드 및 시작
docker compose -f docker-compose.dev.yml up -d --build --remove-orphans

Compose를 사용하지 않는 경우, 명령줄을 통해 직접 실행할 수도 있습니다:

docker run -d --name music-dl \
-p 8080:8080 \
-v $(pwd)/data:/home/appuser/data \
...

비디오 생성 관련 "커버 교체 / 오디오 교체 / 가사 교체 / 비디오 내보내기" 버튼은 Web 설정으로 이전되었습니다. 기본값은 비활성화되어 있으며, 웹 페이지 우측 상단의 설정 패널에서 켤 수 있습니다.

# 검색
./music-dl -k "周杰伦"

TUI 주요 키:

↑/↓ 이동
Space 선택
a 전체 선택/해제
r 체크된 항목 음원 교체
Enter 다운로드
b 뒤로 가기
w 데일리 추천 플레이리스트
q 종료

추가 사용법:

# 도움말 보기
./music-dl -h
# 검색 소스 지정
...

본 프로젝트는 GitHub Actions 워크플로우가 구성되어 있습니다. 코드를 푸시하고 버전 태그(예: v1.0.0)를 달면, 자동으로 .github/workflows/docker.yml이 트리거되어 크로스 플랫폼 이미지(amd64 및 arm64 지원)를 빌드하고 DockerHub로 푸시합니다.

프로젝트는 Gio를 통해 Android APK를 패키징할 수 있으며, 저장소 루트 디렉토리에 다음 세 가지 APK 파일이 생성됩니다:

music-dl_arm64-v8a.apk (권장, 대부분의 Android 기기용)
music-dl_x86_64.apk (x86_64 기기/에뮬레이터용)
music-dl.apk (분할 패키지(Split APK)를 사용할 수 없는 극소수 기기용)

Android APK를 설치한 후, Web 우측 상단의 "설정 (Settings)"에서 "로컬 다운로드 디렉토리 (Local Download Directory)"를 /sdcard/Music으로 변경하는 것을 권장합니다. 이렇게 하면 다운로드된 파일이 시스템 음악 디렉토리로 바로 들어갑니다.

전제 조건:

• Go 설치 및 사용 가능 (1.25+ 권장)
• JDK (17 권장)
• Android SDK 설치됨, 기본 경로: C:\Android
• 사용 가능한 NDK (스크립트가 자동으로 27.0.12077973 설치를 시도함)

명령어 실행:

cd go-music-dl
package_app.bat

스크립트는 자동으로 다음을 수행합니다:

• 현재 Java 환경 (JAVA_HOME/java) 읽기
• Android NDK 감지/설치
• gogio 설치
• music-dl_arm64-v8a.apk, music-dl_x86_64.apk, music-dl.apk 빌드

만약 adb가 감지되면 다음과 같이 설치 명령어를 출력합니다:

adb install -r music-dl.apk

.github/workflows/release.yml에 build-android-apk 작업이 추가되었습니다. 배포 시 windows-latest 환경에서 다음을 수행합니다:

• Go, JDK 17, Android SDK 설치
• platform-tools, platforms;android-33, build-tools;34.0.0, ndk;27.0.12077973 설치
• Android arm/arm64/x86/x86_64용 ffmpeg 및 ffprobe 다운로드
• package_app.bat 실행
• APK 빌드 후 assets/ffmpeg/<abi>/ffmpeg 및 assets/ffmpeg/<abi>/ffprobe 주입, 다시 zipalign 수행 및 배포용 keystore로 서명
• 세 개의 APK가 각각의 ABI에 해당하는 ffmpeg/ffprobe를 포함하고 있는지, 오래된 libffmpeg.so/libffprobe.so 항목이 포함되지 않았는지, 그리고 서명이 유효한지 검증
• music-dl_arm64-v8a.apk, music-dl_x86_64.apk, music-dl.apk를 Actions Artifacts 및 GitHub Release에 업로드

배포 후에는 Releases에서 세 개의 APK를 다운로드할 수 있으며, music-dl_arm64-v8a.apk를 우선적으로 사용하는 것을 권장합니다. 극소수의 기기에서 설치/실행이 불가능한 경우에만 music-dl.apk (분할 패키지 미지원 버전)를 다운로드하십시오.

고버전(34.0.0 이상)의 Android Build-Tools는 이전 버전의 d8.bat 스크립트 호환성 문제가 수정되어 Java 17과 정상적으로 함께 사용할 수 있습니다.

만약 로컬에 여전히 33.0.0 버전이 있다면, 업그레이드 및 이전 버전 정리를 권장합니다:

"C:\Android\cmdline-tools\latest\bin\sdkmanager.bat" "build-tools;34.0.0"

Android Studio를 사용하는 경우, SDK Manager -> SDK Tools에서 "Show Package Details"를 체크한 후 34.0.0 이상의 버전을 설치할 수도 있습니다.

매우 중요: C:\Android\build-tools\ 디렉토리로 이동하여 33.0.0 이전 디렉토리를 삭제하거나 이름을 변경하십시오. 이는 gogio가 이전 버전의 d8을 우선적으로 찾아내는 것을 방지하기 위함입니다.

완료 후 다시 실행하십시오:

cd go-music-dl
package_app.bat

프로젝트는 iOS 빌드 스크립트인 package_ios.sh를 제공합니다.

• macOS (Xcode Command Line Tools 설치 필요)
• Go 설치 및 사용 가능
• 사용 가능한 iOS provisioning profile 및 해당 서명 인증서

cd go-music-dl
chmod +x package_ios.sh
export IOS_APP_ID=com.guohuiyuan.musicdl
...

스크립트는 자동으로 다음을 수행합니다:

• gogio 설치
• provisioning profile을 사용하여 실제 기기용 IPA로 빌드 (출력물: music-dl-ios.ipa)
• 또는 IOS_UNSIGNED_ONLY=1을 사용하여 서명 대기 상태의 실제 기기 아키텍처 패키지 생성 (출력물: music-dl-ios-unsigned.ipa)

music-dl-ios.ipa

: 서명된 실제 기기 설치 패키지이며, IOS_APP_ID와 일치하는 .mobileprovision을 가리키는 IOS_PROVISION_PROFILE이 필요합니다.

music-dl-ios-unsigned.ipa

: 서명이 필요한 실제 기기 아키텍처 패키지로, 사용자가 직접 재서명(re-sign)하는 용도로만 사용되며 직접 설치할 수 없습니다.

릴리스(Releases)가 게시된 후 music-dl-ios-unsigned.ipa를 다운로드할 수 있으며, 서명 관련 secrets를 설정하면 music-dl-ios.ipa도 함께 업로드됩니다.

주의:

music-dl-ios-unsigned.ipa는 직접 설치 가능한 패키지가 아니며, 사용자가 자신의 인증서(certificate)와 프로비저닝 프로파일(provisioning profile)을 사용하여 재서명해야 합니다. GitHub Actions를 통해 서명된 iOS 패키지를 자동으로 배포하려면 IOS_PROVISION_PROFILE_BASE64, IOS_CERTIFICATE_P12_BASE64, 그리고 IOS_CERTIFICATE_PASSWORD를 설정해야 합니다.

본 저장소를 포크(Fork)하여 자신만의 빌드 흐름을 사용하고자 하는 경우:

• 자신의 저장소 Settings -> Secrets and variables -> Actions에서 다음을 추가하세요:

DOCKERHUB_USERNAME: 당신의 DockerHub 사용자 이름
DOCKERHUB_TOKEN: 당신의 DockerHub 액세스 토큰

• docker-compose.yml 파일의 이미지 주소를 자신의 것으로 수정하세요: image: 당신의_사용자명/go-music-dl:latest

곡 카드 내의 "소스 변경(换源)" 기능은 다른 플랫폼에서 더 유사한 버전을 찾습니다:

• 먼저 곡 제목/가수의 유사도를 확인합니다.
• 그다음 재생 시간 차이를 확인합니다 (차이가 너무 크면 건너뜁니다).
• 마지막으로 재생 가능 여부를 탐색합니다.

현재 soda와 fivesing은 건너뜁니다.

웹 페이지에는 NetEase Cloud Music, QQ Music, Kugou, Kuwo Music을 통합하여 보여주는 "오늘의 추천(每日推荐)" 입구가 있습니다.
TUI에서는 입력 화면에서 w를 누르면 추천 플레이리스트를 즉시 가져오며, 엔터를 누르면 상세 정보로 진입합니다.