mixxxtransfer

Mixxx 플레이리스트를 tar로 내보내고 가져오는 도구. mixxxdb.sqlite를 직접 읽고 써서 플레이리스트 · 트랙 메타데이터 · BPM/비트그리드 · CUE/핫큐/루프 · 웨이브 파형 · 크레이트 · Auto DJ 큐 · 재생 히스토리를 다른 PC의 Mixxx 라이브러리로 옮긴다.

CLI(mixxxtransfer)와 GUI(mixxxtransfer-gui) 두 가지 방식으로 쓸 수 있으며, 둘 다 같은 핵심 로직(mixxxtransfer.core)을 공유한다.

내보내고 가져올 수 있는 항목

• 플레이리스트 & 소속 트랙
  • 아티스트/제목/앨범/키/재생시간 등 메타데이터 전체
  • BPM (고정 여부 포함)
  • CUE / 핫큐 / 루프 포인트
  • 웨이브 파형 & 비트그리드 (스키마 버전이 호환될 때)
  • 오디오 파일 원본 (선택, 기본 포함)
• 크레이트 (--include-crates, 일반 크레이트만 — 스마트 크레이트 조건은 대상 없음)
• Auto DJ 큐 (--include-autodj, 트랙 순서만 — 재생 진행 상태는 제외)
• 재생 히스토리 (--include-history, 세션 단위 전체)

타 DJ 소프트웨어(iTunes/Rekordbox 등) 연동은 지원 범위 밖이다.

설치

Python 3.12 이상이 필요하다.

pip install -e .

GUI까지 쓰려면:

pip install -e ".[gui]"

사용법 (CLI)

DB 경로를 지정하지 않으면 플랫폼 기본 위치(Linux: ~/.mixxx/mixxxdb.sqlite, Windows: %LOCALAPPDATA%\Mixxx\mixxxdb.sqlite)를 자동으로 찾는다. 모든 명령에 --db-path로 직접 지정할 수 있다.

# 플레이리스트를 아카이브로 내보내기 (오디오 포함이 기본값)
mixxxtransfer export "내 플레이리스트" playlist.tar

# 오디오는 빼고 메타데이터만, 크레이트/AutoDJ/히스토리도 함께
mixxxtransfer export "내 플레이리스트" playlist.tar --no-audio \
  --include-crates --include-autodj --include-history

# 실제로 쓰지 않고 무엇이 내보내질지 미리 보기
mixxxtransfer export "내 플레이리스트" playlist.tar --dry-run

# 다른 PC에서 가져오기 (실행 전 자동으로 mixxxdb.sqlite를 백업한다)
mixxxtransfer import playlist.tar

# 이름/크기가 같은 기존 트랙을 만났을 때 확인 없이 항상 추가
mixxxtransfer import playlist.tar --yes-to-all

# 수동 백업만
mixxxtransfer backup

mixxxtransfer <명령> --help로 각 명령의 전체 옵션을 볼 수 있다.

사용법 (GUI)

mixxxtransfer-gui

mixxxdb.sqlite 경로를 입력하면 내보내기 탭의 플레이리스트 드롭다운이 자동으로 채워진다. 내보내기 / 가져오기 / 백업 세 개의 탭으로 구성되어 있고, CLI와 동일한 핵심 로직을 그대로 사용한다.

안전장치

• Mixxx 실행 중이면 차단. 프로세스 확인과 DB 파일 잠금 시도를 모두 거쳐, Mixxx가 DB를 쓰고 있을 가능성이 있으면 아무 작업도 진행하지 않는다.
• 가져오기 전 자동 백업. 실행할 때마다 mixxxdb.sqlite를 별도 위치에 타임스탬프를 붙여 백업하고, 기본적으로 최근 5개만 보관한다. 가져오기가 실패하면 이 백업으로 자동 복원한다.
• 트랙 매칭은 해시 우선. 파일명+크기로 후보를 찾은 뒤, 실제 파일을 해싱해 완전히 같을 때만 자동으로 같은 트랙으로 처리한다. 해시가 다르거나 확인할 수 없으면 사용자에게 물어본다(CLI: 프롬프트/--yes-to-all/--no-to-all, GUI: 다이얼로그/라디오 버튼).

언어

기본은 한국어. 영어로 쓰려면 MIXXXTRANSFER_LANG=en을 지정한다 (지정하지 않으면 시스템 로캘이 영어일 때 자동으로 영어를 쓴다).

MIXXXTRANSFER_LANG=en mixxxtransfer export "My Playlist" playlist.tar
MIXXXTRANSFER_LANG=en mixxxtransfer-gui

아카이브 형식

JSON 매니페스트 + 무압축 .tar. 오디오는 audio/<해시8자리>_<파일명>으로 평탄화해 저장하며, 같은 트랙이 여러 플레이리스트에 속해도 한 번만 저장한다.

기준 환경

• Linux (Ubuntu 24.04) & Windows 11 25H2
• Mixxx 2.5.6 (스키마 버전 39 기준. 그 이하 버전은 호환 범위 안에서 지원)

기술 스택

• Python 3.12+
• PySide6 (Qt 6) — GUI
• pytest — 테스트

개발

pip install -e ".[dev]"
pytest
ruff check .

테스트는 117건, mixxxtransfer 패키지 라인 커버리지 100%(pytest --cov=mixxxtransfer --cov-report=term-missing로 확인 가능). 개인 데이터 없이도 전부 재현 가능하도록 tests/dbfactory.py/tests/fixtures/empty_mixxxdb.py로 실제 스키마와 동일한 빈 DB를 직접 구성해 사용하며, sample.mixxxdb.sqlite가 있으면 그것을 쓰는 통합 테스트도 몇 개 추가로 돈다(없으면 자동으로 skip). GUI 테스트는 QT_QPA_PLATFORM=offscreen으로 디스플레이 없이 실행된다.

Windows 단일 실행파일(.exe) 빌드

pip 설치 없이 쓸 수 있는 단일 실행파일을 PyInstaller로 만든다 (Windows 전용 스크립트).

python -m venv .venv
.venv\Scripts\pip install -e ".[dev,gui,build]"
.\packaging\build.ps1            # CLI+GUI 둘 다
.\packaging\build.ps1 -Target cli
.\packaging\build.ps1 -Target gui

결과물은 dist\mixxxtransfer.exe, dist\mixxxtransfer-gui.exe (둘 다 onefile, 추가 설치 없이 실행 가능. 실행 시 임시 폴더에 압축을 풀었다가 종료 시 정리한다). 스펙 파일은 packaging/*.spec, 실제 진입점 래퍼는 packaging/run_cli.py / packaging/run_gui.py에 있다 (PyInstaller가 패키지 내부 모듈을 최상위 스크립트로 착각해 상대 임포트가 깨지는 문제를 피하기 위함).

설계 결정 사항과 상세 근거는 todo.md에 정리되어 있다.

라이선스

GPL-2.0-only (Mixxx와 동일)