# 문제 해결

## Bluetooth 이름이 안 보임

보드는 평소 검색 숨김 상태입니다. 새 휴대폰을 입력으로 등록하려면 웹 믹서의
**Bluetooth 입력 등록 → 검색 허용 켜기**를 누르거나
`sudo radxa-audio discoverable on --seconds 300`을 실행합니다.
정한 시간이 지나면 다시 숨겨집니다. 켜졌는데도 안 보이면
`bluetoothctl show`의 `Discoverable: yes`와 `journalctl -u radxa-bt-pairing`을 확인하세요. 이미 신뢰 등록한 장비는
검색 모드를 계속 켜 두지 않아도 다시 연결할 수 있습니다.

헤드폰을 출력으로 연결하려면 헤드폰 자체의 페어링 모드를 켠 뒤
`sudo radxa-audio scan`을 실행합니다. 헤드폰의 BLE 주소가 아니라
`Bose QC Headphones`처럼 음악 장비로 표시되는 주소를 사용합니다.

## 휴대폰에 ‘연결됨’이지만 출력 선택에 없음

페어링만 됐고 A2DP 오디오 승인/연결이 안 된 경우가 있습니다:

```bash
sudo radxa-audio devices
sudo radxa-audio pair 휴대폰MAC주소
sudo bluealsa-aplay -l
```

`List of CAPTURE Bluetooth Devices`에 휴대폰과 `A2DP (SBC)`가 있으면
Radxa가 휴대폰 소리를 받을 경로가 잡힌 상태입니다. 아이폰에서 출력 목록을
닫았다가 다시 열어 선택합니다.

`List of PLAYBACK Bluetooth Devices`는 Radxa가 소리를 보내는 헤드폰/스피커입니다.
이 두 목록은 입력과 출력을 구별하는 중요한 확인 지점입니다.

## 헤드폰에서 소리가 안 남

```bash
sudo radxa-audio status
sudo journalctl -u radxa-bt-output -u bluealsa -u bluealsa-aplay -n 60 --no-pager
```

- 출력 설정이 `bluetooth`인지 확인합니다.
- 헤드폰이 켜져 있고 PLAYBACK 목록에 나타나는지 확인합니다.
- 휴대폰은 헤드폰에 직접 보내는 대신 Radxa Bluetooth를 선택합니다.
- MacBook은 Radxa AirPlay를 다시 선택합니다.
- 블루투스 출력은 헤드폰 버튼으로도 볼륨을 조절합니다.
- 문제를 분리하려면 `sudo radxa-audio output dac`으로 돌아가 같은 입력이 들리는지 확인합니다.

## AirPlay 무음/끊김

```bash
sudo journalctl -u shairport-sync -u nqptp -n 60 --no-pager
ping -c 20 공유기IP
aplay -l
```

기준 Zero 3W에서는 AIC 드라이버의 Wi-Fi 6(HE)을 끄고 전원 절약을 끈 뒤
끊김이 해결됐습니다. Wi-Fi 6 표준 자체가 원인이라고 단정한 것은 아닙니다.
드라이버/공유기 조합의 호환 문제로 보고 동일 드라이버에만 옵션을 적용합니다.

`--wifi5`로 설치했다면 재부팅 후 다음 값이 `N`인지 확인합니다:

```bash
cat /sys/module/aic8800_fdrv/parameters/he_on
cat /sys/module/aic8800_fdrv/parameters/ps_on
```

다른 무선 드라이버에는 이 경로/옵션이 없습니다.

## 같은 소리를 헤드폰과 스피커에서 듣는데 시차가 남

블루투스 인코딩/무선 전송에는 지연이 추가됩니다. 이 자료는 DAC 또는
블루투스 중 하나를 출력으로 선택하며, 두 출력의 동기 재생은 지원하지 않습니다.

## 여러 입력을 더하면 찢어짐

입력은 감쇠 없이(0 dB) 섞으므로 두 입력이 동시에 크게 재생되면 합이 최대치를 넘을 수 있습니다. 입력 수가 늘어나면
각 기기의 볼륨을 더 낮춰 합산 클리핑을 피해야 합니다. 최대 안정적인
블루투스 동시 입력 수는 보드 컨트롤러/드라이버와 실제 재생으로 검증해야 합니다.

## 설치 실패

오류 메시지와 설치 전 백업 경로를 확인합니다. `apt-get update`의 저장소
버전 확인 요청이나 네트워크 오류부터 해결한 뒤 재실행합니다.

`modinfo snd-aloop` 실패는 해당 Armbian 커널에 ALSA Loopback 모듈이 없는 경우입니다.
커널에 모듈이 준비되기 전에는 블루투스 믹스 출력 설치를 진행하지 않습니다.

소스/서비스를 바꾸지 않고 빌드만 확인하려면, 필요한 개발 패키지가 설치된
보드에서 다음을 실행합니다:

```bash
bash scripts/check-build.sh
```

## 웹 화면에 접속되지 않음

```bash
sudo systemctl status radxa-mixer-web --no-pager
sudo journalctl -u radxa-mixer-web -n 40 --no-pager
```

주소는 `http://radxa-mixer.local`(80번 포트)입니다. 출력 장비가 꺼져 있어도 화면은 접속 가능해야 합니다.
`.local`만 안 열리면 `systemctl status avahi-daemon`과 `hostname`을 확인하고,
게스트 Wi-Fi처럼 기기 간 멀티캐스트가 막힌 네트워크에서는 IP 주소로 접속하세요.
브라우저를 새로고침하면 재시작 후 바뀐 요청 토큰이 갱신됩니다.

## AirPlay 입력이 ‘제어 준비 중’으로 표시됨

`shairport-sync -V`에 `dbus`가 있는지 확인합니다. D-Bus 기능과 이 패키지의
네이티브 볼륨 패치가 없는 기존 바이너리는 웹 볼륨 제어를 지원하지 않습니다.

## Bluetooth 입력을 헤드폰으로 다시 보낼 때 끊김

`journalctl -u bluealsa -u bluealsa-aplay -u radxa-bt-output --since "5 min ago"`
에서 `Missing RTP packets`는 입력 수신 패킷 손실, `underrun`/`overrun`은
오디오 버퍼 오류를 뜻합니다. 수신 손실은 버퍼만 늘려 복구되지 않습니다.
같은 입력을 DAC로 보낼 때와 Bluetooth 출력으로 보낼 때를 비교하세요.
기준 보드에서는 버퍼만 500 ms로 늘려서는 끊김이 남았고, 송신 SBC 품질을
high에서 medium으로 낮춘 뒤(`bluealsa --sbc-quality=medium`) 해결됐습니다.
같은 컨트롤러로 수신과 송신을 동시에 하므로 송신 전송량이 수신 손실에 영향을 줍니다.
SBC medium 적용 후에는 500 ms 버퍼가 필요 없어 믹서(dmix), Bluetooth 입력
(`bluealsa-aplay`), 헤드폰 송신(`alsaloop`) 버퍼를 각각 200 ms로 줄였습니다.
버퍼를 다시 늘리면 지연이 그만큼 늘어나므로, 끊김이 생기면 먼저 로그로
수신 손실인지 버퍼 오류인지 구분하세요.

청취 확인 시에는 `bluealsa-aplay -l`의 PLAYBACK 목록에 헤드폰이 있는지 먼저 봅니다.
없으면 헤드폰이 휴대폰에 직접 연결돼 Radxa를 거치지 않은 소리일 수 있습니다.

## Bluetooth 컨트롤러 점검

기준 AIC 보드에서 데몬/하드웨어 초기화 중 UART 컨트롤러가 오류 상태에 들어가
`/sys/class/bluetooth/hci0`는 있어도 `bluetoothctl list`가 비는 경우를 확인했습니다.
`hciconfig -a`, `btmgmt info`, `dmesg`로 확인하고, Bluetooth 초기화 서비스로
풀리지 않으면 재부팅 후 다시 확인합니다. 페어링 기록을 먼저 삭제하지 마세요.

## 웹의 출력 목록·검색 결과가 비어 있음

`/api/state`의 `issues`에 `Failed to create new json object`가 보이면 BlueZ 기기
속성을 JSON으로 변환하지 못한 것입니다. Apple 기기의 광고 데이터(ManufacturerData)가
원인이었으며, 현재 버전은 필요한 속성만 읽어 이 문제를 피합니다. 오래된 웹 파일이
설치돼 있다면 `sudo bash scripts/install-web.sh`로 갱신하세요.