pandoli365
/
mic
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

AI 규칙 지정

This commit is contained in:
김민서 2026-06-02 11:55:28 +09:00
parent a8e261fe97
commit 282d02cbc2
5 changed files with 317 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
README.md
View File

@ -1,23 +1,35 @@
# mic
Orange Pi Zero 2W 기반 Wi-Fi 라발리에 마이크 송신기와 Mac 수신/믹서 프로젝트입니다.
Orange Pi Zero 2W를 사용하는 Wi-Fi 라발리에 마이크 송신기와 Mac 수신/믹서 프로젝트입니다.
## 먼저 읽어야 할 문서
이 프로젝트에 참여하는 AI는 어떤 작업을 시작하기 전에 반드시 아래 문서를 먼저 읽어야 합니다.
- `docs/00-ai-collaboration-rules.md`: AI 협업 기본 규칙
특히 사용자가 계획을 확정하고 실행을 지시하기 전까지는 코드를 만들지 않습니다. 구현 언어는 C++입니다.
```text
USB lavalier -> Orange Pi Zero 2W -> 2.4/5 GHz Wi-Fi router -> Mac mixer
USB 라발리에 마이크 -> Orange Pi Zero 2W -> 2.4/5 GHz Wi-Fi 공유기 -> Mac 믹서
```
## Structure
## 프로젝트 구조
- `client/`: Orange Pi에서 실행하는 마이크 송신기
- `server/`: Mac에서 실행하는 UDP 수신/믹서
- `os/`: Orange Pi OS 이미지 보관 위치
- `docs/`: 보드 세팅과 스트리밍 실행 가이드
- `client/`: Orange Pi에서 실행할 마이크 송신기 소프트웨어
- `server/`: Mac에서 실행할 수신/믹서 소프트웨어
- `os/`: Orange Pi에 설치할 OS 이미지 보관 위치
- `docs/`: 보드 설정과 실행 절차 문서
- `plans/`: AI 작업 플랜 기록 위치
## Current Direction
## 현재 방향
- OS: official Orange Pi Debian 12 Bookworm Server, Linux 6.1
- Language: C++
- 임베디드 보드: Orange Pi Zero 2W
- OS 기준: Orange Pi 공식 Debian 12 Bookworm Server, Linux 6.1
- 구현 언어: C++
## Docs
## 문서
- `docs/01-orange-pi-os.md`
- `docs/00-ai-collaboration-rules.md`: AI 협업 기본 규칙
- `docs/01-orange-pi-os.md`: Orange Pi Zero 2W OS 설치 준비
- `plans/README.md`: 플랜 파일 작성 형식

174
docs/00-ai-collaboration-rules.md Normal file
View File

@ -0,0 +1,174 @@
# AI 협업 기본 규칙
이 문서는 이 프로젝트에 참여하는 모든 AI와 사람이 공통으로 따라야 할 기본 규칙입니다.
프로젝트의 방향이 흔들리지 않도록, 새로 참여하는 AI는 작업을 시작하기 전에 반드시 이 문서를 먼저 읽어야 합니다.
## 프로젝트 요약
이 프로젝트는 Orange Pi Zero 2W를 마이크 송신기로 사용하고, Mac을 수신기이자 믹서로 사용하는 Wi-Fi 오디오 시스템입니다.
```text
USB 라발리에 마이크 -> Orange Pi Zero 2W -> 2.4/5 GHz Wi-Fi 공유기 -> Mac 수신/믹서
```
## 현재 기준
- 임베디드 장비: Orange Pi Zero 2W
- 저장장치: microSD Ultra 32GB
- 권장 OS: Orange Pi 공식 Debian 12 Bookworm Server, Linux 6.1
- 구현 언어: C++
- `client/`: Orange Pi에서 실행할 송신기 소프트웨어
- `server/`: Mac에서 실행할 수신기/믹서 소프트웨어
- `os/`: Orange Pi에 설치할 OS 이미지 보관 위치
- `docs/`: 프로젝트 문서
- `plans/`: AI 작업 플랜 기록 위치
## 가장 중요한 규칙
사용자가 명확하게 계획을 확정하고 실행하라고 말하기 전까지는 코드를 만들지 않습니다.
다음과 같은 작업은 사용자 승인 없이 진행하지 않습니다.
- C++ 소스 코드 생성
- 빌드 시스템 생성
- 테스트 코드 생성
- 패키지 설치 스크립트 생성
- 기존 코드 구조 변경
- 프로토콜, 아키텍처, 라이브러리 선택 확정
문서 정리, 현재 상태 확인, 파일 목록 확인, OS 이미지 검증처럼 코드가 아닌 준비 작업은 사용자의 요청 범위 안에서만 수행합니다.
## 언어 규칙
- 구현 언어는 C++입니다.
- Python 기반 송신기, 수신기, 테스트 코드는 만들지 않습니다.
- 임시 분석이나 파일 확인을 위해 로컬 도구를 사용할 수는 있지만, 프로젝트 산출물로 Python 코드를 추가하지 않습니다.
- 문서는 기본적으로 한국어로 작성합니다.
- 외부 링크, 파일명, 명령어, 패키지명은 원문을 유지합니다.
## 작업 방식
AI는 작업을 시작하기 전에 먼저 현재 저장소 상태를 확인해야 합니다.
권장 확인 항목:
- 현재 브랜치와 변경사항
- `README.md`
- `docs/00-ai-collaboration-rules.md`
- 관련 디렉터리의 파일 목록
- 사용자가 직접 만든 변경사항 여부
작업 중 사용자가 만든 변경사항을 되돌리지 않습니다. 변경사항이 작업과 충돌하면 되돌리기보다 사용자에게 확인합니다.
## 계획 우선 원칙
코드 구현이 필요한 단계에서는 먼저 계획을 작성합니다.
계획에는 다음 항목을 포함합니다.
- 목표
- 대상 환경
- 사용할 언어와 라이브러리 후보
- 송신기와 수신기의 역할 분리
- 오디오 캡처 방식
- 네트워크 전송 방식
- 지연 시간과 안정성 목표
- 검증 방법
사용자가 계획을 확인하고 실행을 지시한 뒤에만 구현을 시작합니다.
## 플랜 파일 작성 규칙
AI가 작업을 진행할 때는 `plans/` 폴더에 자신의 작업 플랜을 기록합니다.
기본 절차:
1. 자신의 대화 또는 작업 단위를 식별할 임시 고유 UUID를 생성합니다.
2. `plans/{uuid}.md` 파일을 생성합니다.
3. 해당 파일에 자신이 할 일 목록을 작성합니다.
4. 작업을 순차적으로 진행하면서 같은 `.md` 파일의 할 일 상태와 메모를 수정합니다.
5. 작업 완료 후 결과 요약을 같은 파일에 남깁니다.
플랜 파일은 작업의 흐름을 남기기 위한 기록입니다. 사용자가 실행을 지시하지 않은 코드 구현을 정당화하는 용도로 사용하지 않습니다.
권장 형식은 `plans/README.md`를 따릅니다.
## 설계 원칙
초기 목표는 복잡한 기능보다 안정적인 오디오 경로 확인입니다.
우선순위:
1. Orange Pi에서 USB 라발리에 마이크 인식
2. Mac에서 UDP 수신 가능 여부 확인
3. 단일 송신기 오디오 전송 검증
4. 지연 시간과 끊김 확인
5. 다중 송신기 믹싱
6. 압축, 동기화, 자동 검색, UI 같은 확장 기능 검토
초기 설계에서 지나치게 복잡한 기능을 먼저 넣지 않습니다.
## OS 이미지 규칙
`os/` 폴더에는 Orange Pi OS 이미지 파일을 보관할 수 있습니다.
다운로드한 원본 압축 파일인 `.7z`는 커밋할 수 있습니다. 단, 압축을 풀어서 나온 실제 디스크 이미지 파일은 용량이 크고 Git에 적합하지 않으므로 커밋하지 않습니다.
커밋하지 않는 파일 예시:
```text
os/*.img
os/*.img.*
os/*/*.img
os/*/*.img.*
```
일반 ARM64 Debian/Ubuntu 이미지가 아니라 Orange Pi Zero 2W 전용 이미지를 사용해야 합니다.
## 외부 정보 확인
OS 다운로드 링크, 보드 지원 상태, 라이브러리 지원 여부처럼 시간이 지나며 바뀔 수 있는 정보는 가능한 최신 공식 자료를 확인합니다.
우선순위:
1. Orange Pi 공식 문서
2. 라이브러리 공식 문서
3. 운영체제 공식 문서
4. 커뮤니티 자료
커뮤니티 자료를 사용할 경우 공식 자료가 아니라는 점을 명확히 표시합니다.
## 문서 수정 규칙
문서를 수정할 때는 다음 기준을 지킵니다.
- 한국어로 자연스럽게 작성합니다.
- 실제로 결정된 내용과 후보를 구분합니다.
- 추측은 결정처럼 쓰지 않습니다.
- 명령어는 검증된 경우에만 절차로 적습니다.
- 아직 구현되지 않은 기능을 이미 있는 기능처럼 설명하지 않습니다.
## 금지 사항
다음 작업은 하지 않습니다.
- 사용자 승인 없는 코드 생성
- 사용자 승인 없는 대규모 구조 변경
- Python 기반 구현 추가
- 압축 해제된 `.img` OS 이미지 파일 커밋
- 보드 전용 이미지가 아닌 일반 ARM64 이미지를 권장
- 확인되지 않은 성능 수치를 확정값처럼 작성
- 사용자가 만든 변경사항 되돌리기
## 새 AI를 위한 첫 행동
새로 참여한 AI는 다음 순서로 시작합니다.
1. `README.md`를 읽습니다.
2. `docs/00-ai-collaboration-rules.md`를 읽습니다.
3. 현재 Git 변경사항을 확인합니다.
4. 사용자의 최신 요청을 확인합니다.
5. 작업이 필요한 경우 임시 UUID를 만들고 `plans/{uuid}.md`에 할 일 목록을 작성합니다.
6. 코드가 필요한 작업이면 먼저 계획을 제시합니다.
7. 사용자가 실행을 지시하기 전까지 구현하지 않습니다.

69
docs/01-orange-pi-os.md
View File

@ -1,44 +1,67 @@
# Orange Pi Zero 2W OS setup
# Orange Pi Zero 2W OS 설치 준비
## Recommended image
## 권장 이미지
Use the official Debian 12 Bookworm server image for Orange Pi Zero 2W:
Orange Pi Zero 2W용 공식 Debian 12 Bookworm Server 이미지를 우선 사용합니다.
```text
orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.7z
Orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.7z
```
Orange Pi's Zero 2W wiki lists Debian 12 Bookworm with Linux 6.1 as supported, and its Linux 6.1 driver table marks Wi-Fi, Type-C USB2.0, TF card boot, and related board features as OK.
이 이미지를 권장하는 이유는 다음과 같습니다.
Official references:
- 서버 이미지라 불필요한 데스크톱 환경이 없습니다.
- 마이크 송신기처럼 headless로 동작하는 장비에 적합합니다.
- Linux 6.1 기반 공식 이미지라 Zero 2W의 Wi-Fi, USB, TF 카드 부팅 등 기본 보드 기능을 기대할 수 있습니다.
- 이후 C++ 기반 송신기 소프트웨어를 올리기 좋은 가벼운 출발점입니다.
공식 참고 링크:
- https://www.orangepi.org/orangepiwiki/index.php/Orange_Pi_Zero_2W
- https://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-Zero-2W.html
- http://www.orangepi.cn/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-Zero-2W.html
## Flashing
## 이미지 파일 확인
1. Download the image into `os/`.
2. Extract the `.7z` file to get the `.img`.
3. Flash the `.img` to the microSD with Balena Etcher, Raspberry Pi Imager, or another verified imaging tool.
4. Mount the flashed boot/root partition and configure first-run Wi-Fi before inserting it into the Orange Pi.
`os/` 폴더에 다운로드한 압축 파일을 보관합니다.
## Headless Wi-Fi first boot
```text
os/Orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.7z
```
On the flashed SD card, find:
압축 파일 안에는 보통 다음 파일들이 들어 있습니다.
```text
Orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.img
Orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.img.sha
```
`.img` 파일은 microSD에 실제로 기록할 OS 이미지이고, `.sha` 파일은 이미지 무결성 검증에 사용합니다.
## microSD에 기록하기
1. `.7z` 압축 파일을 풉니다.
2. 나온 `.img` 파일을 확인합니다.
3. Balena Etcher, Raspberry Pi Imager, Win32 Disk Imager 같은 도구로 `.img` 파일을 microSD에 기록합니다.
4. 기록이 끝나면 microSD를 다시 마운트해서 첫 부팅용 Wi-Fi 설정을 준비합니다.
## Headless Wi-Fi 첫 부팅 설정
키보드와 모니터 없이 처음 부팅하려면, 기록된 microSD의 boot 파티션에서 다음 파일을 찾습니다.
```text
/boot/orangepi_first_run.txt.template
```
Copy it to:
이 파일을 복사해서 아래 이름으로 만듭니다.
```text
/boot/orangepi_first_run.txt
```
Then set the Wi-Fi fields. `os/orangepi_first_run.example.txt` contains a local example for Korea region code `KR`.
그다음 Wi-Fi 관련 값을 수정합니다. 예시는 `os/orangepi_first_run.example.txt`에 있습니다.
The important values are:
중요한 값은 다음과 같습니다.
```text
FR_net_change_defaults=1
@ -49,19 +72,27 @@ FR_net_wifi_key='YOUR_WIFI_PASSWORD'
FR_net_wifi_countrycode='KR'
```
## First login
한국에서 사용할 경우 국가 코드는 `KR`로 둡니다.
For official Debian/Ubuntu Orange Pi images, the usual default accounts are:
## 첫 로그인
Orange Pi 공식 Debian/Ubuntu 이미지의 기본 계정은 보통 다음과 같습니다.
```text
orangepi / orangepi
root / orangepi
```
Change the password on first login.
첫 로그인 후에는 반드시 비밀번호를 변경합니다.
```bash
passwd
sudo passwd root
```
## 다음 단계
OS 부팅과 SSH 접속이 확인되면, USB 라발리에 마이크 인식 여부와 Wi-Fi 연결 안정성을 확인합니다.
송신기와 수신기 소프트웨어는 이후 C++ 기준으로 설계하고 구현합니다.

43
os/README.md
View File

@ -1,26 +1,43 @@
# OS image storage
# OS 이미지 보관 위치
Put the Orange Pi Zero 2W OS image files here, but do not commit them.
이 폴더는 Orange Pi Zero 2W에 설치할 OS 이미지 파일을 보관하는 곳입니다.
Recommended first image:
다운로드한 원본 `.7z` 파일은 이 폴더에 보관하고 Git에 커밋할 수 있습니다. 단, 압축을 풀어서 나온 `.img` 파일은 용량이 크고 Git에 적합하지 않으므로 커밋하지 않습니다.
`.gitignore`에서는 다음 파일만 제외합니다.
```text
orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.7z
os/*.img
os/*.img.*
os/*/*.img
os/*/*.img.*
```
Why this one:
## 권장 이미지
- Debian 12 Bookworm server image keeps the transmitter small and headless.
- Linux 6.1 is listed by Orange Pi as supporting Wi-Fi, Type-C USB2.0, TF card boot, and the usual board peripherals on Zero 2W.
- A server image gives us a small, headless baseline for the future C++ transmitter.
첫 설치 이미지로는 다음 파일을 권장합니다.
Official pages:
```text
Orangepizero2w_1.0.0_debian_bookworm_server_linux6.1.31.7z
```
## 권장 이유
- Debian 12 Bookworm Server 이미지는 가볍고 headless 장비에 적합합니다.
- 마이크 송신기처럼 GUI가 필요 없는 장비에서는 서버 이미지가 더 안정적인 출발점입니다.
- Linux 6.1 기반 공식 이미지라 Orange Pi Zero 2W의 Wi-Fi, USB, TF 카드 부팅 등 기본 기능을 기대할 수 있습니다.
- 이후 C++ 기반 송신기 소프트웨어를 올리기 좋은 기준 환경입니다.
## 공식 참고 링크
- https://www.orangepi.org/orangepiwiki/index.php/Orange_Pi_Zero_2W
- https://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-Zero-2W.html
- http://www.orangepi.cn/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-Zero-2W.html
Notes:
## 주의사항
- Use the Zero 2W-specific image only. A generic ARM64 Debian or Ubuntu image will usually miss the board kernel/DTB/Wi-Fi pieces.
- The official download page may redirect to external storage such as Google Drive.
- Keep `.7z`, `.img`, `.xz`, and similar files in this folder locally; `.gitignore` excludes them.
- 일반 ARM64 Debian/Ubuntu 이미지가 아니라, 반드시 Orange Pi Zero 2W 전용 이미지를 사용해야 합니다.
- 보드 전용 이미지가 아니면 커널, DTB, Wi-Fi 드라이버 문제로 부팅이나 네트워크 연결이 실패할 수 있습니다.
- 공식 다운로드 페이지가 Google Drive 같은 외부 저장소로 연결될 수 있습니다.
- 다운로드한 `.7z` 원본 압축 파일은 이 폴더에 보관하고 Git에 올릴 수 있습니다.
- 압축을 풀어서 나온 `.img` 파일은 이 폴더에 보관하더라도 Git에는 올리지 않습니다.

39
plans/README.md Normal file
View File

@ -0,0 +1,39 @@
# 플랜 폴더
이 폴더는 AI가 작업을 진행하기 전에 자신의 작업 계획을 기록하는 곳입니다.
각 AI는 작업 단위마다 임시 고유 UUID를 만들고, 아래 형식의 파일을 생성합니다.
```text
plans/{uuid}.md
```
플랜 파일에는 자신이 할 일 목록을 작성하고, 작업을 순차적으로 진행하면서 상태를 계속 갱신합니다.
예시:
```text
plans/00000000-0000-0000-0000-000000000000.md
```
## 기본 형식
```markdown
# 작업 플랜
- UUID: `{uuid}`
- 작업자: `{AI 이름 또는 식별자}`
- 생성 시각: `{YYYY-MM-DD HH:mm}`
- 요청 요약: `{사용자의 최신 요청 요약}`
## 할 일
- [ ] 현재 요청 확인
- [ ] 관련 문서 확인
- [ ] 작업 수행
- [ ] 결과 검증
- [ ] 완료 내용 정리
```
작업이 진행되면 완료된 항목을 `[x]`로 바꾸고, 필요한 메모를 같은 파일에 남깁니다.