Add reproducible Radxa AirPlay and Bluetooth mixer setup

README.md

@@ -0,0 +1,195 @@
+# Radxa 무선 오디오 믹서
+
+AirPlay 2와 블루투스 오디오 입력을 동시에 섞어 USB DAC 또는 블루투스
+헤드폰·스피커 한 대로 출력하는 설치 자료입니다.
+
+검증 기준은 **Radxa Zero 3W / RAM 1 GB / Armbian 26.8.3 / Debian 13 trixie /
+커널 6.1.115-vendor-rk35xx**입니다. 다른 Radxa도 같은 OS와 오디오·블루투스
+지원이 있으면 이 구성으로 시도할 수 있지만, 모든 보드의 무선 드라이버를
+검증한 것은 아닙니다. 설치기는 Debian 13 외의 OS에서는 작업을 중단합니다.
+
+## 구성
+
+```text
+Mac/iPhone의 AirPlay 2 ── Shairport Sync ─┐
+                                        ├─ ALSA 스테레오 믹서 ─ USB DAC
+휴대폰 등의 Bluetooth ── BlueALSA ───────┘                  또는
+                                                Loopback → Bluetooth 헤드폰/스피커
+```
+
+- AirPlay 2: Shairport Sync **5.5.2**, NQPTP **1.2.8**, 공유 메모리 규격 smi10.
+- Bluetooth: Debian의 BlueALSA 패키지. 기준 보드 버전 **4.3.1**.
+- 수신과 송신은 A2DP 음악 프로필을 사용합니다. 기준 보드에서는 SBC로 연결됐습니다.
+- DAC 출력은 44.1 kHz / 스테레오 / 16비트, 블루투스용 가상 믹서는 48 kHz입니다.
+- 각 입력을 6 dB 낮춰 두 입력을 합칠 여유를 둡니다. 세 입력 이상은 각 기기 볼륨을
+  추가로 낮추세요. 지연 없는 실시간 녹음/악기 모니터링용 구성은 아닙니다.
+- 각 송신 기기의 볼륨으로 믹스 비율을 바꿉니다.
+- 출력은 DAC 또는 블루투스 중 하나를 선택합니다. 양쪽 동시 출력은 구현하지 않았습니다.
+
+## 1. 새 보드 준비
+
+1. Debian 13 기반 Armbian을 설치하고 인터넷에 연결합니다.
+2. USB DAC를 꽂고 `aplay -l`에서 카드 이름을 확인합니다.
+3. 이 폴더 전체를 보드에 복사합니다. `sources/`도 필요합니다.
+
+맥에서 실행할 예:
+
+```bash
+scp -r /Users/jsahn/Personal_works/Radxa_MIXER root@새보드IP:/root/
+ssh root@새보드IP
+```
+
+그다음 보드에서:
+
+```bash
+cd /root/Radxa_MIXER
+aplay -l
+sudo bash install.sh --name "Radxa Desk" --dac hw:CARD=Audio,DEV=0
+```
+
+`Audio`는 현재 Realtek USB DAC의 ALSA 카드 ID입니다. 새 DAC가 `Device`라면
+`--dac hw:CARD=Device,DEV=0`으로 바꾸세요. `card 1` 같은 숫자는 부팅마다 바뀔 수
+있으므로 이름을 사용합니다. 새 보드의 장치 이름은 기존 `Radxa Audio`와 구별해 주세요.
+
+**동일한 AIC 드라이버의 Zero 3W**에서 이전처럼 AirPlay가 끊긴다면:
+
+```bash
+sudo bash install.sh --name "Radxa Desk" --dac hw:CARD=Audio,DEV=0 --wifi5
+```
+
+`--wifi5`는 `aic8800_fdrv`의 `ps_on=0 he_on=0`을 부팅 설정으로 저장합니다.
+다른 드라이버에는 적용하지 않으며, 지원 옵션이 없으면 설치를 중단합니다.
+설정 적용은 다음 재부팅부터입니다. 설치 중 자동으로 재부팅하지 않습니다.
+
+설치에는 apt 인터넷 연결이 필요합니다. 공식 소스는 이 폴더에 포함돼 있어
+GitHub에 접속할 필요가 없습니다. 1 GB 보드의 빌드 메모리를 고려해 기본은
+`make -j 1`이며 몇 분 이상 걸릴 수 있습니다. OS 전체 업그레이드는 하지 않습니다.
+
+기본 출력은 **DAC**입니다. Wi-Fi 비밀번호, USB gadget 주소 `10.55.0.1`,
+netplan/NetworkManager 설정은 이 설치기가 변경하지 않습니다.
+
+## 2. AirPlay 사용
+
+MacBook 또는 아이폰의 출력에서 설치할 때 정한 이름을 선택합니다.
+Mac과 Radxa는 Bonjour/mDNS가 통하는 같은 네트워크에 있어야 합니다.
+게스트 Wi-Fi의 기기 격리 기능이 켜져 있으면 발견되지 않을 수 있습니다.
+
+## 3. 휴대폰을 블루투스 입력으로 연결
+
+보드의 SSH 터미널에서:
+
+```bash
+sudo radxa-audio pair-input --seconds 120
+```
+
+- 터미널을 열어 둔 채 휴대폰 Bluetooth 설정에서 `Radxa Desk Bluetooth`를 선택합니다.
+- 터미널에 본인 휴대폰의 오디오 서비스 승인 질문이 나오면 `yes`를 입력합니다.
+- 완료되면 `quit`을 입력합니다. 검색/페어링 모드는 종료 시 자동으로 닫힙니다.
+- 휴대폰을 신뢰 장치로 등록해, 다음 연결에서 같은 승인 대기가 생기지 않도록 합니다.
+
+```bash
+sudo radxa-audio devices
+sudo radxa-audio pair 휴대폰MAC주소
+```
+
+이미 페어링돼 있으면 `pair` 명령은 해당 상태를 확인하고 신뢰 등록 및 오디오
+연결을 진행합니다. 휴대폰의 출력 목록에서 `Radxa Desk Bluetooth`를 선택하세요.
+
+## 4. 블루투스 출력 장비 연결 및 변경
+
+보스 QC SC는 전원 스위치를 Bluetooth 표시 쪽으로 **약 3초** 유지해
+`Ready to connect` 안내와 파란 LED 점멸이 나오도록 합니다.
+다른 장비는 제조사의 페어링 모드를 켜세요.
+
+```bash
+sudo radxa-audio scan --seconds 30
+sudo radxa-audio pair AA:BB:CC:DD:EE:FF --output
+```
+
+`AA:BB:CC:DD:EE:FF`를 검색 결과의 **헤드폰/스피커 주소**로 바꿉니다.
+이 명령은 페어링 → 신뢰 등록 → 음악 프로필 연결 → 출력 전환을 진행합니다.
+이후 다른 헤드폰으로 바꾸려면 새 헤드폰을 검색하고 같은 명령을 실행하면 됩니다.
+
+이미 등록한 장비로 전환:
+
+```bash
+sudo radxa-audio output bluetooth AA:BB:CC:DD:EE:FF
+```
+
+마지막으로 선택한 블루투스 장비를 다시 사용:
+
+```bash
+sudo radxa-audio output bluetooth
+```
+
+DAC로 복귀:
+
+```bash
+sudo radxa-audio output dac
+```
+
+출력 전환 후 AirPlay를 다시 선택해야 할 수 있습니다. 블루투스 출력 장비가
+연결되지 않으면 **현재 DAC 출력을 바꾸기 전에 오류로 중단**합니다.
+서비스 시작 중 실패하면 변경 직전 설정으로 복구합니다.
+
+헤드폰을 믹서 출력으로 시험할 때는 헤드폰을 휴대폰이나 Mac에 직접 연결한
+경로 대신 Radxa 경로를 사용하세요. 헤드폰의 멀티포인트 자동 전환이 끼어들면
+믹서의 소리가 아닌 다른 기기의 소리를 들을 수 있습니다.
+
+## 5. 일상 관리
+
+```bash
+sudo radxa-audio status                     # 현재 출력/서비스/오디오 연결
+sudo radxa-audio devices                    # Bluetooth 목록 + DAC 목록
+sudo radxa-audio name "Radxa Living Room"   # AirPlay/블루투스 표시 이름
+sudo radxa-audio dac hw:CARD=Device,DEV=0   # 다른 DAC로 설정
+sudo radxa-audio apply                      # 저장한 설정 다시 적용
+```
+
+이전의 `radxa-audio-output dac` / `bose` 명령도 호환 래퍼로 제공합니다.
+`bose`는 마지막으로 설정한 블루투스 출력 장비를 뜻하며, 보스 주소가 고정돼 있지 않습니다.
+
+관리 설정: `/etc/radxa-audio/mixer.json`.
+관리 명령은 여기에 저장한 값을 기준으로 ALSA/systemd 설정을 생성합니다.
+`/etc/asound.conf`나 서비스 파일을 직접 편집하면 다음 관리 명령에서 덮어쓸 수 있으므로,
+이름·DAC·출력 변경은 위 명령을 사용하세요.
+
+## 6. 백업과 복구
+
+설치 전 기존 파일과 서비스 상태는 `/var/backups/radxa-audio-install/날짜-번호/`에
+저장됩니다. 설치 실패 시 이 상태로 자동 복구를 시도합니다.
+
+설치 완료 후에도 원래 상태로 복구할 수 있습니다:
+
+```bash
+sudo python3 scripts/backup.py restore /var/backups/radxa-audio-install/실제백업이름
+```
+
+복구는 설치기가 관리하는 설정·로컬 바이너리·서비스 상태를 대상으로 합니다.
+apt로 추가한 의존 패키지와 블루투스 페어링 기록은 유지합니다.
+운영 중 장비 변경 전 설정 백업은 `/var/backups/radxa-audio/`에 별도로 저장됩니다.
+
+## 파일 안내
+
+| 파일 | 용도 |
+|---|---|
+| `install.sh` | 새 보드 설치, 빌드, 서비스 설정, 실패 시 복구 |
+| `scripts/radxa-audio.py` | 페어링/출력/이름/DAC 관리 |
+| `scripts/backup.py` | 설치 전 백업/복원 |
+| `scripts/check-build.sh` | 서비스 변경 없이 고정 소스 빌드 확인 |
+| `sources/*.bundle`, `manifest.json` | 공식 Git 소스, 릴리스 태그, 커밋, SHA-256 |
+| `tests/test_manager.py` | 입력 검증, 안전한 전환, 실패 복구 검사 |
+| `TROUBLESHOOTING.md` | 검색/연결/무음/끊김 문제 해결 |
+| `VALIDATION.md` | 실제 검증 범위와 남은 검증 |
+| `reference/` | 기존 보드 설정 참고. 새 보드에 그대로 복사하지 않습니다. |
+
+## 원본 프로젝트
+
+- [Shairport Sync](https://github.com/mikebrady/shairport-sync)
+- [NQPTP](https://github.com/mikebrady/nqptp)
+- [BlueALSA](https://github.com/arkq/bluez-alsa)
+- [BlueALSA와 dmix/Loopback 구성](https://github.com/arkq/bluez-alsa/wiki/Using-bluealsa-with-dmix)
+- [Bose QC SC 페어링 안내](https://www.bose.com/p/headphones/bose-quietcomfort-sc-headphones/QCSC-HEADPHONEARN.html)
+
+Git bundle 안에 각 원본 프로젝트의 라이선스 파일도 포함됩니다.
+이 설치 자료에는 개인 Wi-Fi 비밀번호나 블루투스 링크 키를 포함하지 않았습니다.