TL;DR

Go Music DL은 Go 백엔드와 모듈화된 플랫폼 파서를 사용해 10개 이상의 음악 소스를 병렬 검색하고 Web·TUI·데스크톱·모바일에서 동일한 검색·재생·다운로드 워크플로를 제공하는 통합 도구이다. 검색 결과는 유사도와 재생 가능성, 길이 근접성을 기준으로 자동 정렬하며 필요시 소스 간 자동 교체(换源)를 수행하고, 로컬 파일은 SQLite 인덱스와 ffprobe 보완으로 수천 곡 단위에서 빠르게 검색되도록 설계되었다. FFmpeg가 설치된 환경에서는 커버·가사 임베딩이 가능해 파일 완결도를 높일 수 있으며, Docker 이미지와 Releases에서 제공되는 Android APK로 손쉽게 배포·실행할 수 있다. 플랫폼별 로그인·유료 음원 제약과 외부 API 변경은 기능에 영향을 주는 한계이며, FFmpeg 미설치 시 임베딩 기능은 비활성화된다.

주요 기능

• 다중 인터페이스를 제공해 브라우저 기반 Web UI, 터미널 기반 TUI, 그리고 네이티브 데스크톱·모바일 앱에서 동일한 검색·재생·다운로드 기능을 사용할 수 있다. Web UI는 관리자용 설정·쿠키 관리·歌单 분류를 제공하고 TUI는 키보드 중심의 대량 작업에 최적화되어 있다. 데스크톱 애플리케이션은 내부적으로 로컬 HTTP 서비스와 통신해 네이티브 창으로 웹을 렌더링한다.
• 플랫폼 집계 검색으로 네이버·QQ·酷狗·Bilibili·咪咕 등 10개 이상의 소스에서 단곡·歌单·专辑을 병렬 검색하고 각 소스의 메타데이터와 음원 URL을 통합하여 결과를 표준화한다. 검색 시 유사도, 재생 가능성, 길이 근접성으로 자동으로 우선순위를 매기고 필요에 따라 소스 간 교체(换源)를 시도한다. 이 과정은 병렬 요청과 서버 측 캐싱으로 응답 지연을 줄인다.
• 로컬 음악 관리 기능은 다운로드 디렉터리를 스캔해 SQLite 인덱스에 저장하고 ffprobe로 누락된 메타를 보완하며 내장 커버·가사 우선 추출 로직을 통해 목록을 빠르게 로드한다. 인덱스는 경로·파일크기·수정시간을 키로 삼아 메타데이터 캐시를 유지하므로 반복 조회 시 ffprobe 호출을 회피한다. 캐시 만료 시에는 백그라운드 비동기 재스캔을 수행해 UI 응답성을 보장한다.
• 다운로드 파이프라인은 Range 탐지로 파일 크기·비트레이트를 표시하고 FFmpeg가 설치된 경우에는 커버·가사 임베딩(embed)을 선택적으로 수행한다. 기본 동작은 스트리밍 친화적인 플로우로서 내장된 Range 지원과 단편화(resume)를 허용해 미리듣기와 동시에 빠른 다운로드를 가능하게 한다. FFmpeg 미설치 환경에서는 임베딩 단계를 건너뛰고 원본 음원만 저장한다.

어떻게 동작하는가

프로젝트는 Go 기반의 백엔드(core 패키지)에서 각 플랫폼별 파서와 다운로드 로직을 구현하고 music-lib 라이브러리를 통해 플랫폼별 공통 인터페이스로 추상화한다. Web 모드는 Gin 기반 라우팅으로 템플릿과 정적 파일을 서빙하며 TUI는 Bubble Tea를 사용해 터미널 상호작용을 처리한다. 데스크톱 번들은 Rust(Tao/Wry)로 네이티브 창을 띄우고 내부적으로 로컬 HTTP(기본 127.0.0.1:37777)로 백엔드와 통신해 UI·파일 IO·FFmpeg 호출을 조율한다.

해결 문제

분산된 중국·글로벌 음악 플랫폼에서 곡·歌单·专辑을 각각 별도 방법으로 찾아야 하는 불편을 통합 검색과 링크 파싱으로 해결한다. 다중 소스의 병렬 검색과 자동 교차 소스 탐색으로 재생 가능하고 음질이 높은 소스를 자동으로 찾는 과정을 단축한다. 또한 로컬 다운로드·인덱싱·메타데이터 보완 기능을 결합해 대량 파일 관리를 일관된 UI로 수행하게 한다.

지금 주목받는 이유

다중 플랫폼의 음원 접근 제한과 음질·로그인 제약이 지속되는 가운데, 이 프로젝트는 무료로 다양한 소스의 무손실 다운로드와 편리한 로컬 관리를 통합해 실사용자 기반에서 주목을 받았다. GitHub Release에서 Android APK에 FFmpeg를 내장하는 등 모바일 지원을 강화한 점이 최근 사용성 증가의 직접적 원인으로 보인다. 또한 다중 인터페이스(TUI/Web/데스크톱)를 제공해 다양한 사용자층에서 채택이 용이하다.

차별점

• 웹·TUI·네이티브 앱을 같은 백엔드로 지원해 동일한 기능을 서로 다른 사용 환경에서 유지한다. 이 구조는 단일 바이너리(Go)와 플랫폼별 래퍼(Rust/Gio)를 조합해 배포 복잡도를 낮춘다. 데스크톱 APK는 Android ABI별로 FFmpeg를 내장해 모바일 환경에서도 메타데이터 임베딩을 가능하게 했다.
• 다수 플랫폼을 위한 소스별 파서와 링크 파싱 로직을 내장하고 music-lib로 공통 인터페이스를 추상화해 새로운 플랫폼 추가 시 재사용 가능한 플러그인 형태로 확장할 수 있다. 검색 결과는 유사도·길이·가용성 기준으로 자동 정렬되고 실패한 소스는 자동으로 대체 소스 탐색을 시도한다. 이로 인해 수동으로 소스를 전환하는 단계를 줄였다.
• 로컬 음악을 '일등 검색 소스'로 취급하는 점과 SQLite 기반의 파일 인덱싱, ffprobe를 통한 메타데이터 보완을 결합해 수천 곡 규모에서도 검색과 목록 로딩을 빠르게 유지한다. 캐시는 파일 변경 추적으로 무효화되고 백그라운드 재검사가 비동기적으로 처리되어 UI 지연을 최소화한다. 결과적으로 로컬 파일과 온라인 소스의 혼합 검색이 실무적으로 매끄럽게 작동한다.

사용 사례

• 개인 저장용으로 여러 음원 사이트에서 무손실 음원을 일괄 수집하고 메타데이터·커버·가사를 파일에 통합해 오프라인 라이브러리를 구성할 때 유용하다. FFmpeg가 설치된 환경에서는 임베딩 옵션을 사용해 플레이어 호환성을 높일 수 있다. 다운로드된 파일은 지정한 템플릿 구조로 자동 분류되어 백업과 관리가 편리하다.
• 네트워크가 불안정하거나 GUI가 없는 서버 환경에서는 TUI 또는 CLI 모드로 대량 다운로드 작업을 자동화하고, Docker 배포를 통해 서버 기반 장기 백업이나 미디어 허브를 구축하는 용도로 사용할 수 있다. 스케줄러나 외부 스크립트와 결합해 주기적 미디어 수집 파이프라인을 구성할 수 있다.
• 개발자나 호스팅 운영자는 Docker 이미지와 CI 빌드 워크플로를 이용해 자체 호스팅 서비스로 배포하거나 포크하여 플랫폼별 파서 개선 및 커스터마이징을 수행할 수 있다. GitHub Actions 설정으로 크로스 플랫폼 빌드를 자동화해 배포 효율을 확보할 수 있다.

시작하기

데스크톱 사용자는 Releases에서 플랫폼에 맞는 실행 파일을 내려받아 압축을 풀고 실행하면 로컬에서 즉시 Web UI 기반의 네이티브 경험을 얻는다. 서버나 개발 환경에서는 바이너리로 ./music-dl web 명령을 실행하거나 제공된 docker-compose.yml을 사용해 docker compose up -d로 서비스를 기동하면 http://localhost:8080에서 접근 가능하다. Android APK는 릴리스에 FFmpeg 내장 버전이 제공되어 추가 설치 없이도 일부 메타데이터 기능을 이용할 수 있다.

요구사항

• Go 빌드가 필요한 로컬 빌드 환경에서는 Go가 설치되어야 하며(README 권장 1.25+), Android 빌드를 위해서는 JDK 17과 Android SDK/NDK가 필요하다. 빌드 스크립트는 NDK 설치를 자동 시도하나 사전 환경 구성이 있으면 안정성이 높아진다. Docker 배포 시에는 호스트에 Docker·Docker Compose가 설치되어 있어야 한다.
• FFmpeg와 ffprobe는 메타데이터 임베딩과 비MP3 포맷 처리, 음악 길이·비트레이트 탐지 기능에 필요하며, Docker 이미지와 Android APK 빌드에서는 이미지/패키지에 따라 이미 포함되거나 별도 설치가 요구될 수 있다. FFmpeg가 없으면 임베딩 관련 기능은 자동으로 비활성화되고 기본 다운로드는 유지된다. ffprobe는 로컬 음악의 탐지·보완용으로 사용되므로 로컬 메타 보완을 원하면 설치가 권장된다.
• 데스크톱 GUI(Windows)에서 정상 작동하려면 WebView2 런타임이 필요하며 설치되어 있지 않으면 애플리케이션 창이 빈 페이지로 나오거나 초기 실행이 지연된다. README에서 WebView2 설치 링크와 해결 방법을 안내하고 있어 사전 환경 구성이 권장된다. Android에서는 READ_MEDIA_AUDIO 권한이 필요하며 앱에서 해당 권한을 동적으로 요청한다.

이미지 분석