시작 / 설치
README KO
Twistable Music Desktop HQ Version v0.1.15-test / Windows Desktop [v0.1.13 Native launcher / YouTube transport fix] - Normal launch: Twistable.exe (native Windows GUI launcher, no…
Twistable Music Desktop HQ
Version v0.1.15-test / Windows Desktop
[v0.1.13 Native launcher / YouTube transport fix]
- Normal launch: Twistable.exe (native Windows GUI launcher, no CMD/VBS)
- v0.1.12 VBS launcher is retired because Windows security policy can block scripts.
- Mini Player PLAY button is now controlled by the visible tab:
* MP3 tab -> local QMediaPlayer
* YouTube tab -> selected saved YouTube item
- First YouTube PLAY loads and starts the selected saved URL.
- Loaded YouTube PLAY toggles play/pause.
- YouTube and MP3 transport state no longer overwrite each other after tab switching.
- YouTube WebEngine autoplay setting and embed error reporting improved.
- 미니 플레이어 가사 숨김 시 RADIAL PULSE 원형 재생 프로그래시브 표시
- 중앙 진행률 + 재생/일시정지 pulse 상태 연동
- 앱 내부 FFmpeg/yt-dlp/PowerShell subprocess 무콘솔 실행
- RUN_TWISTABLE_SILENT.vbs 및 APPLY_SILENT_SHORTCUT.vbs 추가
[목표]
서버 업로드 없이 PC에서 음악을 관리하고 BS-RoFormer로 보컬/반주를 고품질 분리하는 개인용 데스크탑 음악 앱입니다.
원음 파일과 원본 영상 파일은 절대 수정하지 않습니다.
[주요 기능]
1. MP3/WAV/FLAC/M4A/AAC/OGG/WMA/OPUS 다중 등록 및 폴더 일괄 등록
2. ID3/메타데이터 기반 제목/가수/앨범 자동 인식 + 파일명 추정
3. ORIGINAL / INST / VOCAL 즉시 전환
4. BS-RoFormer 최고음질 우선 + 여러 모델 선택
5. PC 환경 자동 감지 및 AI 장치 자동 선택
6. 분리 결과 FLOAT WAV 캐시 저장
7. 같은 원음+같은 모델 캐시 재사용
8. LRCLIB 온라인 가사 검색 / 후보 선택 / 가사 삭제
9. LRC 시간 동기화 + 일반 가사 AUTO SYNC 노래방 표시
10. 오디오 비주얼 6종
11. SQLite 로컬 음악 라이브러리
12. AI 반주 생성 대기열 + 진행률/ETA 학습
13. 로컬 미디어 변환: WAV/FLAC/M4A/AAC/OGG/OPUS/WMA 등 오디오 + MP4/MKV/WebM 등 영상 → MP3/WAV/FLAC 다중 변환 → 자동등록
14. 온라인 미디어: URL → VIDEO 또는 AUDIO 다운로드
15. 온라인 AUDIO 완료 후 음악 라이브러리 자동등록
16. 온라인 다운로드 대기열 / 항목별 진행률 / 속도 / ETA / 실패원인 / 취소
17. 온라인 엔진(yt-dlp) 독립 업데이트
[v0.1.10 UI / 로컬 변환 / 미니 플레이어]
- Windows 기본 흰색 탭과 메뉴가 보이던 문제를 전역 다크 스타일로 수정했습니다.
- 버튼/입력창/탭/박스는 둥근 모서리를 제거하고 직각 + 1px 얇은 라인으로 통일했습니다.
- 미니 플레이어 실행 시 메인 창은 완전히 숨고, [메인 창]으로 복귀합니다.
- 미니 플레이어에 4px 초박형 재생 진행 막대와 LOCAL/YOUTUBE 상태 표시를 추가했습니다.
- WAV -> MP3 포함, 대부분의 일반 오디오를 MP3/WAV/FLAC으로 변환할 수 있습니다.
- 여러 파일 선택 및 폴더 추가 일괄 변환을 지원하며 기본 출력은 MP3 320kbps입니다.
[v0.1.9 미니 플레이어 / 라이브러리 UI]
- 메인 음악 리스트 다크 UI 개선: 흰색 교차행 제거, 선택행 강조, ★/☆ 즐겨찾기, 현재곡 ▶ 표시
- 상단 [▣ 미니 플레이어] 추가
- MP3 추가 / 폴더 추가 / 들으면서 현재곡 즐겨찾기 추가
- MP3 즐겨찾기 목록은 SQLite에 즉시 저장되며 앱 재시작 후에도 유지
- 재생 방식: 연속 듣기 / 전체 한번 듣기 / 한 곡 반복
- 미니 플레이어에서 가사 보임/숨김
- 항상 위(Always on Top), 이전/다음, 재생/일시정지, 탐색, 볼륨
- YouTube URL 저장 목록 추가: 주소 저장 / 삭제 / 순서 이동 / 이전·다음
- YouTube 제목/채널명은 온라인 엔진이 준비되어 있으면 백그라운드에서 자동 확인
- Qt WebEngine 사용 가능 시 앱 내부 YouTube 플레이어 + 비디오 보임/숨김
- 내부 재생이 어려운 영상은 [YouTube에서 열기] 사용
- 미니 창 크기, 반복모드, 가사/비디오 표시, 항상 위 상태 자동 기억
[v0.1.8 온라인 후처리 수정]
- v0.1.7에서 imageio-ffmpeg 실행파일의 폴더를 yt-dlp에 넘기면서 ffmpeg.exe/ffprobe.exe를 찾지 못하던 문제 수정
- .runtime\ffmpeg\ffmpeg.exe + ffprobe.exe를 자동 설치하고 yt-dlp에 정확한 폴더를 전달
- FFmpeg/FFprobe가 없으면 URL 다운로드를 시작하기 전에 즉시 안내하여 WEBM만 받은 뒤 실패하는 상황 방지
- 기존에 이미 받은 WEBM은 삭제하지 않아도 되며, 런타임 복구 후 같은 URL을 실행하면 기존 파일을 재사용하여 MP3/WAV/FLAC 후처리 가능
- REPAIR_ONLINE_MEDIA.cmd 추가: 전체 Python 환경을 다시 설치하지 않고 온라인 미디어 런타임만 복구
- yt-dlp 터미널 ANSI 진행 로그를 숨기고 앱 진행률 표시만 사용
[v0.1.7~v0.1.8 온라인 미디어]
상단 [온라인 미디어] 버튼 또는 메뉴 [온라인 미디어] → [URL 가져오기 · VIDEO / AUDIO...]를 사용합니다.
기본 흐름:
URL 가져오기
→ VIDEO 다운로드 또는 AUDIO 다운로드 선택
→ 형식/화질 선택
→ 다운로드 목록에 추가
→ 순차 다운로드
→ AUDIO는 완료 후 음악 라이브러리 자동등록
AUDIO 출력:
- MP3 320kbps 변환
- WAV
- FLAC
VIDEO 출력:
- MP4
- MKV
- WEBM
- 화질: 1080p / 720p / 480p / 최고 화질
대기열:
- URL 여러 개를 한 줄에 하나씩 붙여넣기 가능
- 각 URL별 진행률 표시
- 다운로드 속도 / 예상 남은시간 / 받은 용량 표시
- 실패한 URL은 이유를 해당 행과 로그에 표시
- 전체 대기열 취소 가능
- 같은 파일이 이미 존재하면 yt-dlp의 기존 파일 처리 규칙을 사용하여 불필요한 덮어쓰기를 피함
저장 위치:
%LOCALAPPDATA%\TwistableMusicDesktop\downloads\audio
%LOCALAPPDATA%\TwistableMusicDesktop\downloads\video
사용자가 다른 보관 폴더로 변경할 수 있습니다.
라이브러리 등록 원칙:
- AUDIO 결과: 자동 등록
- VIDEO 결과: 영상 파일로만 보관, 음악 라이브러리에는 넣지 않음
음질 안내:
MP3 320kbps는 출력 호환성을 위한 설정입니다. 원본 온라인 오디오가 그보다 낮은 비트레이트/손실 음원이라면 실제 음질이 320kbps 수준으로 좋아지는 것은 아닙니다.
WAV/FLAC로 변환해도 이미 손실된 원본 정보가 복원되지는 않습니다.
온라인 엔진 업데이트:
사이트가 변경되어 기존 다운로드 엔진이 동작하지 않을 때
- 메뉴 [온라인 미디어] → [온라인 엔진 업데이트...]
또는
- UPDATE_ONLINE_ENGINE.cmd
를 실행합니다.
업데이트 완료 후 앱을 재시작합니다.
[v0.1.7~v0.1.8 온라인 다운로드 제한]
- 일반 공개 미디어 URL 중심으로 동작합니다.
- 비공개/회원전용/삭제/지역제한/연령제한/로그인 확인/봇 확인 등이 걸린 URL은 실패할 수 있습니다.
- v0.1.8-test에는 브라우저 쿠키 추출, 계정 비밀번호 저장, DRM 우회, 보호조치 우회 기능을 넣지 않았습니다.
- 사이트 구조가 변경되면 온라인 엔진 업데이트가 필요할 수 있습니다.
- 본인이 이용할 권리가 있는 미디어에 사용하십시오.
[v0.1.6 로컬 미디어 가져오기]
상단 [로컬 미디어 변환] 버튼 또는 메뉴 [로컬 미디어 변환]을 사용합니다.
- 입력: MP4 / MKV / WebM
- 출력: MP3 320kbps / WAV 24-bit PCM / FLAC 무손실 컨테이너
- 기본 저장 폴더: %LOCALAPPDATA%\TwistableMusicDesktop\imports
- 저장 폴더 변경 가능
- 여러 파일 순차 변환
- 변환 진행률 표시
- 완료 오디오는 음악 라이브러리에 자동 등록
- 원본 영상은 삭제/변경하지 않음
[PC 환경 자동 수용]
특정 CPU/RAM/GPU 모델을 기준으로 고정하지 않습니다.
앱 실행 시 현재 PC의 CPU/코어/클럭/RAM/GPU/VRAM/PyTorch CUDA 지원을 읽고 AI 장치를 자동 판정합니다.
첫 곡 ETA는 현재 PC 기준으로 계산하고, 완료 후 그 PC의 실제 처리시간을 저장하여 다음 ETA를 보정합니다.
다른 PC로 옮기면 새 PC 환경을 다시 읽고 해당 PC 기준으로 새로 학습합니다.
[설치 방식]
Python 공식 설치 EXE를 실행하지 않습니다.
앱 폴더의 로컬 uv.exe가 앱 전용 Python 3.12와 .venv를 관리합니다.
- py.exe 필요 없음
- YouTube JS 처리용 Deno 2.8.1도 .runtime\deno에 앱 전용으로 설치하며 Windows PATH에는 등록하지 않음
- 온라인 후처리용 정식 ffmpeg.exe + ffprobe.exe를 .runtime\ffmpeg에 앱 전용으로 설치하며 Windows PATH에는 등록하지 않음
- 시스템 Python PATH 필요 없음
- 기존 Python 삭제/변경 없음
- Windows PATH 변경 없음
- Python 레지스트리 등록 없음
[설치 / 업데이트]
v0.1.7-test에서 업데이트하는 경우 SETUP_WINDOWS.cmd를 한 번 다시 실행하거나 REPAIR_ONLINE_MEDIA.cmd를 실행하십시오. v0.1.8은 yt-dlp 후처리에 필요한 ffmpeg.exe와 ffprobe.exe를 앱 전용 런타임으로 설치합니다.
1. ZIP 압축 해제 또는 기존 테스트 폴더에 덮어쓰기
2. SETUP_WINDOWS.cmd 실행
3. Setup completed successfully 확인
4. NVIDIA CUDA 사용을 원하는 PC는 INSTALL_NVIDIA_CUDA128.cmd 실행
5. RUN_TWISTABLE.cmd 실행
[데이터 위치]
DB/AI 결과/모델/변환 결과/온라인 다운로드 기본 폴더:
%LOCALAPPDATA%\TwistableMusicDesktop
프로그램 폴더를 교체해도 기존 음악 DB와 AI 결과는 유지됩니다.
[문제 확인]
CHECK_SYSTEM.cmd 실행
설치 로그: logs\setup_*.log
[주의]
- AI 보컬 제거는 원본 멀티트랙과 완전히 동일하지 않으며 곡에 따라 보컬 잔향/악기 손실이 일부 발생할 수 있습니다.
- LRCLIB 및 온라인 미디어 사이트는 외부 서비스이므로 인터넷 연결과 서비스 상태/정책/구조 변경에 따라 결과가 달라질 수 있습니다.
- v0.1.8-test는 Windows 실기 테스트 버전입니다.
Version v0.1.15-test / Windows Desktop
[v0.1.13 Native launcher / YouTube transport fix]
- Normal launch: Twistable.exe (native Windows GUI launcher, no CMD/VBS)
- v0.1.12 VBS launcher is retired because Windows security policy can block scripts.
- Mini Player PLAY button is now controlled by the visible tab:
* MP3 tab -> local QMediaPlayer
* YouTube tab -> selected saved YouTube item
- First YouTube PLAY loads and starts the selected saved URL.
- Loaded YouTube PLAY toggles play/pause.
- YouTube and MP3 transport state no longer overwrite each other after tab switching.
- YouTube WebEngine autoplay setting and embed error reporting improved.
- 미니 플레이어 가사 숨김 시 RADIAL PULSE 원형 재생 프로그래시브 표시
- 중앙 진행률 + 재생/일시정지 pulse 상태 연동
- 앱 내부 FFmpeg/yt-dlp/PowerShell subprocess 무콘솔 실행
- RUN_TWISTABLE_SILENT.vbs 및 APPLY_SILENT_SHORTCUT.vbs 추가
[목표]
서버 업로드 없이 PC에서 음악을 관리하고 BS-RoFormer로 보컬/반주를 고품질 분리하는 개인용 데스크탑 음악 앱입니다.
원음 파일과 원본 영상 파일은 절대 수정하지 않습니다.
[주요 기능]
1. MP3/WAV/FLAC/M4A/AAC/OGG/WMA/OPUS 다중 등록 및 폴더 일괄 등록
2. ID3/메타데이터 기반 제목/가수/앨범 자동 인식 + 파일명 추정
3. ORIGINAL / INST / VOCAL 즉시 전환
4. BS-RoFormer 최고음질 우선 + 여러 모델 선택
5. PC 환경 자동 감지 및 AI 장치 자동 선택
6. 분리 결과 FLOAT WAV 캐시 저장
7. 같은 원음+같은 모델 캐시 재사용
8. LRCLIB 온라인 가사 검색 / 후보 선택 / 가사 삭제
9. LRC 시간 동기화 + 일반 가사 AUTO SYNC 노래방 표시
10. 오디오 비주얼 6종
11. SQLite 로컬 음악 라이브러리
12. AI 반주 생성 대기열 + 진행률/ETA 학습
13. 로컬 미디어 변환: WAV/FLAC/M4A/AAC/OGG/OPUS/WMA 등 오디오 + MP4/MKV/WebM 등 영상 → MP3/WAV/FLAC 다중 변환 → 자동등록
14. 온라인 미디어: URL → VIDEO 또는 AUDIO 다운로드
15. 온라인 AUDIO 완료 후 음악 라이브러리 자동등록
16. 온라인 다운로드 대기열 / 항목별 진행률 / 속도 / ETA / 실패원인 / 취소
17. 온라인 엔진(yt-dlp) 독립 업데이트
[v0.1.10 UI / 로컬 변환 / 미니 플레이어]
- Windows 기본 흰색 탭과 메뉴가 보이던 문제를 전역 다크 스타일로 수정했습니다.
- 버튼/입력창/탭/박스는 둥근 모서리를 제거하고 직각 + 1px 얇은 라인으로 통일했습니다.
- 미니 플레이어 실행 시 메인 창은 완전히 숨고, [메인 창]으로 복귀합니다.
- 미니 플레이어에 4px 초박형 재생 진행 막대와 LOCAL/YOUTUBE 상태 표시를 추가했습니다.
- WAV -> MP3 포함, 대부분의 일반 오디오를 MP3/WAV/FLAC으로 변환할 수 있습니다.
- 여러 파일 선택 및 폴더 추가 일괄 변환을 지원하며 기본 출력은 MP3 320kbps입니다.
[v0.1.9 미니 플레이어 / 라이브러리 UI]
- 메인 음악 리스트 다크 UI 개선: 흰색 교차행 제거, 선택행 강조, ★/☆ 즐겨찾기, 현재곡 ▶ 표시
- 상단 [▣ 미니 플레이어] 추가
- MP3 추가 / 폴더 추가 / 들으면서 현재곡 즐겨찾기 추가
- MP3 즐겨찾기 목록은 SQLite에 즉시 저장되며 앱 재시작 후에도 유지
- 재생 방식: 연속 듣기 / 전체 한번 듣기 / 한 곡 반복
- 미니 플레이어에서 가사 보임/숨김
- 항상 위(Always on Top), 이전/다음, 재생/일시정지, 탐색, 볼륨
- YouTube URL 저장 목록 추가: 주소 저장 / 삭제 / 순서 이동 / 이전·다음
- YouTube 제목/채널명은 온라인 엔진이 준비되어 있으면 백그라운드에서 자동 확인
- Qt WebEngine 사용 가능 시 앱 내부 YouTube 플레이어 + 비디오 보임/숨김
- 내부 재생이 어려운 영상은 [YouTube에서 열기] 사용
- 미니 창 크기, 반복모드, 가사/비디오 표시, 항상 위 상태 자동 기억
[v0.1.8 온라인 후처리 수정]
- v0.1.7에서 imageio-ffmpeg 실행파일의 폴더를 yt-dlp에 넘기면서 ffmpeg.exe/ffprobe.exe를 찾지 못하던 문제 수정
- .runtime\ffmpeg\ffmpeg.exe + ffprobe.exe를 자동 설치하고 yt-dlp에 정확한 폴더를 전달
- FFmpeg/FFprobe가 없으면 URL 다운로드를 시작하기 전에 즉시 안내하여 WEBM만 받은 뒤 실패하는 상황 방지
- 기존에 이미 받은 WEBM은 삭제하지 않아도 되며, 런타임 복구 후 같은 URL을 실행하면 기존 파일을 재사용하여 MP3/WAV/FLAC 후처리 가능
- REPAIR_ONLINE_MEDIA.cmd 추가: 전체 Python 환경을 다시 설치하지 않고 온라인 미디어 런타임만 복구
- yt-dlp 터미널 ANSI 진행 로그를 숨기고 앱 진행률 표시만 사용
[v0.1.7~v0.1.8 온라인 미디어]
상단 [온라인 미디어] 버튼 또는 메뉴 [온라인 미디어] → [URL 가져오기 · VIDEO / AUDIO...]를 사용합니다.
기본 흐름:
URL 가져오기
→ VIDEO 다운로드 또는 AUDIO 다운로드 선택
→ 형식/화질 선택
→ 다운로드 목록에 추가
→ 순차 다운로드
→ AUDIO는 완료 후 음악 라이브러리 자동등록
AUDIO 출력:
- MP3 320kbps 변환
- WAV
- FLAC
VIDEO 출력:
- MP4
- MKV
- WEBM
- 화질: 1080p / 720p / 480p / 최고 화질
대기열:
- URL 여러 개를 한 줄에 하나씩 붙여넣기 가능
- 각 URL별 진행률 표시
- 다운로드 속도 / 예상 남은시간 / 받은 용량 표시
- 실패한 URL은 이유를 해당 행과 로그에 표시
- 전체 대기열 취소 가능
- 같은 파일이 이미 존재하면 yt-dlp의 기존 파일 처리 규칙을 사용하여 불필요한 덮어쓰기를 피함
저장 위치:
%LOCALAPPDATA%\TwistableMusicDesktop\downloads\audio
%LOCALAPPDATA%\TwistableMusicDesktop\downloads\video
사용자가 다른 보관 폴더로 변경할 수 있습니다.
라이브러리 등록 원칙:
- AUDIO 결과: 자동 등록
- VIDEO 결과: 영상 파일로만 보관, 음악 라이브러리에는 넣지 않음
음질 안내:
MP3 320kbps는 출력 호환성을 위한 설정입니다. 원본 온라인 오디오가 그보다 낮은 비트레이트/손실 음원이라면 실제 음질이 320kbps 수준으로 좋아지는 것은 아닙니다.
WAV/FLAC로 변환해도 이미 손실된 원본 정보가 복원되지는 않습니다.
온라인 엔진 업데이트:
사이트가 변경되어 기존 다운로드 엔진이 동작하지 않을 때
- 메뉴 [온라인 미디어] → [온라인 엔진 업데이트...]
또는
- UPDATE_ONLINE_ENGINE.cmd
를 실행합니다.
업데이트 완료 후 앱을 재시작합니다.
[v0.1.7~v0.1.8 온라인 다운로드 제한]
- 일반 공개 미디어 URL 중심으로 동작합니다.
- 비공개/회원전용/삭제/지역제한/연령제한/로그인 확인/봇 확인 등이 걸린 URL은 실패할 수 있습니다.
- v0.1.8-test에는 브라우저 쿠키 추출, 계정 비밀번호 저장, DRM 우회, 보호조치 우회 기능을 넣지 않았습니다.
- 사이트 구조가 변경되면 온라인 엔진 업데이트가 필요할 수 있습니다.
- 본인이 이용할 권리가 있는 미디어에 사용하십시오.
[v0.1.6 로컬 미디어 가져오기]
상단 [로컬 미디어 변환] 버튼 또는 메뉴 [로컬 미디어 변환]을 사용합니다.
- 입력: MP4 / MKV / WebM
- 출력: MP3 320kbps / WAV 24-bit PCM / FLAC 무손실 컨테이너
- 기본 저장 폴더: %LOCALAPPDATA%\TwistableMusicDesktop\imports
- 저장 폴더 변경 가능
- 여러 파일 순차 변환
- 변환 진행률 표시
- 완료 오디오는 음악 라이브러리에 자동 등록
- 원본 영상은 삭제/변경하지 않음
[PC 환경 자동 수용]
특정 CPU/RAM/GPU 모델을 기준으로 고정하지 않습니다.
앱 실행 시 현재 PC의 CPU/코어/클럭/RAM/GPU/VRAM/PyTorch CUDA 지원을 읽고 AI 장치를 자동 판정합니다.
첫 곡 ETA는 현재 PC 기준으로 계산하고, 완료 후 그 PC의 실제 처리시간을 저장하여 다음 ETA를 보정합니다.
다른 PC로 옮기면 새 PC 환경을 다시 읽고 해당 PC 기준으로 새로 학습합니다.
[설치 방식]
Python 공식 설치 EXE를 실행하지 않습니다.
앱 폴더의 로컬 uv.exe가 앱 전용 Python 3.12와 .venv를 관리합니다.
- py.exe 필요 없음
- YouTube JS 처리용 Deno 2.8.1도 .runtime\deno에 앱 전용으로 설치하며 Windows PATH에는 등록하지 않음
- 온라인 후처리용 정식 ffmpeg.exe + ffprobe.exe를 .runtime\ffmpeg에 앱 전용으로 설치하며 Windows PATH에는 등록하지 않음
- 시스템 Python PATH 필요 없음
- 기존 Python 삭제/변경 없음
- Windows PATH 변경 없음
- Python 레지스트리 등록 없음
[설치 / 업데이트]
v0.1.7-test에서 업데이트하는 경우 SETUP_WINDOWS.cmd를 한 번 다시 실행하거나 REPAIR_ONLINE_MEDIA.cmd를 실행하십시오. v0.1.8은 yt-dlp 후처리에 필요한 ffmpeg.exe와 ffprobe.exe를 앱 전용 런타임으로 설치합니다.
1. ZIP 압축 해제 또는 기존 테스트 폴더에 덮어쓰기
2. SETUP_WINDOWS.cmd 실행
3. Setup completed successfully 확인
4. NVIDIA CUDA 사용을 원하는 PC는 INSTALL_NVIDIA_CUDA128.cmd 실행
5. RUN_TWISTABLE.cmd 실행
[데이터 위치]
DB/AI 결과/모델/변환 결과/온라인 다운로드 기본 폴더:
%LOCALAPPDATA%\TwistableMusicDesktop
프로그램 폴더를 교체해도 기존 음악 DB와 AI 결과는 유지됩니다.
[문제 확인]
CHECK_SYSTEM.cmd 실행
설치 로그: logs\setup_*.log
[주의]
- AI 보컬 제거는 원본 멀티트랙과 완전히 동일하지 않으며 곡에 따라 보컬 잔향/악기 손실이 일부 발생할 수 있습니다.
- LRCLIB 및 온라인 미디어 사이트는 외부 서비스이므로 인터넷 연결과 서비스 상태/정책/구조 변경에 따라 결과가 달라질 수 있습니다.
- v0.1.8-test는 Windows 실기 테스트 버전입니다.