SoniCloud Recorder SDK
언어: English | 简体中文
녹음 카드와 완벽한 BLE 통합 레퍼런스입니다.
SoniCloud Recorder는 하드웨어 벤더, 소프트웨어 개발자 및 시스템 통합업체를 위한 오픈 소스 레퍼런스 프로젝트입니다. 이 프로젝트는 녹음기 하드웨어를 BLE 프로토콜 SDK, 크로스 플랫폼 통합 샘플, 데스크톱 데모와 결합하여 팀이 장치 연결에서 녹음, 전송, 전사(transcription), 제품 통합으로 이동하는 것을 돕습니다.
<img src="https://raw.githubusercontent.com/SonicloudTech/sonicloud_opensdk/HEAD/img/%E5%BD%95%E9%9F%B3%E5%8D%A1%E7%89%87.png" alt="SoniCloud recorder card" width="480" style="max-width: 100%; height: auto;">
프로젝트 개요 (Project overview)
이 프로젝트는 녹음기 하드웨어 통합에 대한 계층적 접근 방식을 시연합니다. 표준 BLE 명령어, 벤더 어댑테이션 레이어(vendor adaptation layer), 그리고 크로스 플랫폼 SDK 래퍼가 포함됩니다. 녹음 카드(recorder card)는 오디오를 캡처하고 저장하며; SDK는 BLE 세션, 프로토콜 트래픽, 장치 상태 및 데이터 스트림을 관리합니다; 애플리케이션은 UI, 오디오 디코딩, 스토리지, 전사 및 비즈니스 통합을 담당합니다. 서비스 UUID(service UUID), 특성(characteristics), 패킷화(packetization), 개인 명령(private commands) 등 칩셋 간의 차이점은 어댑터 레이어 내에 유지됩니다.
포함된 내용 (What is included)
| 리소스 | 대상 사용자 | 내용 |
|---|
| Mobile SDKs | Android, iOS, HarmonyOS 및 Flutter 개발자 | 플랫폼 래퍼, BLE 디스커버리 및 연결, 녹음 제어, 실시간 오디오, 파일 전송, Wi-Fi, OTA, 장치 정보 및 이벤트 콜백 |
| ... | | |
기능 (Capabilities)
- 안드로이드(Android), iOS, HarmonyOS, 그리고 Flutter에서 스캔, 연결, 녹음 제어 및 장치 이벤트 수신을 위한 통합 인터페이스 모델.
- 명시적인 애플리케이션 확인(confirmation)을 통해 하드웨어 키로 녹음 시작, 일시 중지(pause), 재개(resume), 및 정지 이벤트를 처리.
- 애플리케이션 소유의 디코딩, 재생, 자동 음성 인식(ASR) 또는 회의록 서비스용 원시 16kHz 모노 Opus 프레임.
- 파일 목록 조회, 파일 이름 및 오프셋별 분할 다운로드, 재개 지원(resume support), 유효성 검사(validation), 로컬 저장소 관리 및 삭제 기능.
- 배터리, 용량, 펌웨어 버전, 일련번호(serial number), 인증 코드, 녹음 상태, 지속 시간 및 게인 정보.
- BLE 제어의 Wi-Fi 설정 후, 녹음 또는 펌웨어 전송을 위한 Wi-Fi/TCP 전송 방식 사용. BLE는 펌웨어 페이로드(payload)가 아닌 OTA 제어에 사용됨.
- 스캔, 연결 확인, 녹음 제어, 파일 다운로드, 재생 및 스트리밍 기능을 위한 Windows/macOS 데스크톱 데모 제공.
- sherpa-onnx 기반의 격리된 오프라인 음성 엔진(Voice Engine)을 포함하며, SenseVoice ASR, Kokoro 다국어 TTS, 모델 매니페스트, SHA-256 검증 및 Flutter/Android/iOS 브릿지 진입점(bridge entry points) 제공.
- 통합 작업을 중복하지 않으면서 칩셋, 장치 모델 및 산업 애플리케이션을 추가할 수 있는 표준 명령어와
VendorAdapter 경계(boundary) 제공.
리포지토리 레이아웃
sonicloud_opensdk/
├── pnote-android-sdk/ # Android AAR
├── pnote-ios-sdk/ # iOS static library and header
...
5분 만에 데스크톱 데모 실행하기
요구 사항: Python 3.10 이상, 작동하는 BLE 어댑터, 연결 준비가 된 녹음기 카드.
cd pnote-web-win&Mac-demo
python -m venv .venv
source .venv/bin/activate
...
브라우저에서 http://127.0.0.1:8000을 엽니다. 웹 콘솔은 중국어와 영어를 지원하며, 우측 상단의 선택기를 사용하여 언어를 전환할 수 있습니다. 또한 명령줄 REPL도 확인할 수 있습니다:
record> scan
record> connect 0
record> smoke
...
전체 명령어 목록은 데스크톱 데모 README를 참조하세요. 오프라인 음성 기능은 음성 인식(Speech-to-text)—텍스트 음성 변환(text-to-speech)에 분리되어 있으며, 웹 페이지는 선택 사항으로 유지됩니다:
cd "../Speech-to-text—text-to-speech"
pip install -r requirements-python.txt
python scripts/fetch_voice_models.py --all
...
모델 아카이브는 Speech-to-text—text-to-speech/models/manifest.json에 고정되어 있으며, 공식 sherpa-onnx 릴리스에서 다운로드하고 추출 전에 SHA-256으로 검증됩니다. 모델 가중치는 의도적으로 일반 Git 기록에서 제외되었습니다. 기존 SDK는 변경되지 않습니다.
Windows/macOS 웹 데모
데스크톱 데모는 장치 검색(device discovery), 연결 확인(connection checks), 녹음 제어(recording control), 파일 다운로드(file downloads), WAV 재생(WAV playback), 실시간 스트리밍(real-time streaming)을 위한 명령줄 REPL과 브라우저 기반 웹 콘솔을 모두 제공합니다. 오프라인 ASR/TTS는 Speech-to-text—text-to-speech 아래에 별도로 유지되므로 기존 SDK는 변경되지 않습니다.
SoniCloud recorder BLE console
모바일 통합
통합하기 전에, 권한(permissions), 의존성(dependencies), 초기화(initialization), 콜백(callbacks), 오디오 처리(audio processing), 재개 가능한 파일 전송(resumable file transfer), 그리고 OTA 수용 테스트(OTA acceptance testing)에 대한 내용은 SDK 통합 가이드를 읽어보세요. 크로스 벤더 표준화 모델의 경우, 이 리포지토리에 포함된 프로토콜 노트와 문서를 참조하세요.
Flutter
cd pnote-sdk-flutter-demo-main
flutter pub get
flutter run
블루투스(Bluetooth), 녹음, Wi-Fi 및 OTA를 검증하기 위해 실제 장치를 사용하세요. 주요 통합 진입점은 lib/provider_record_pen.dart이며, Flutter 데모 README를 참고하세요.
Android
Android AAR 파일을 앱의 app/libs 또는 src/main/libs 디렉토리에 복사하세요. fileTree 의존성과 SDK의 RxJava, Retrofit, EventBus 및 기타 필수 의존성을 추가한 다음, 다음 코드를 호출하세요:
PNote.init(context, deviceDataListener);
PNote.startSearch();
PNote.connectDevice(name, address);
콜백에는 JSON 장치 이벤트, 실시간 Opus 데이터, 파일 Opus 데이터가 포함됩니다. 전체 API는 Android SDK 가이드를 참조하십시오.
iOS
Xcode에 libPNote.a와 PNode.h를 추가하고, WindBleDelegate를 구현하며, startSearch 및 connectDeviceAndAddress와 같은 API를 호출합니다. 전체 API 및 OTA 워크플로우는 iOS SDK 가이드를 참조하십시오.
HarmonyOS
HarmonyOS SDK는 har_recordersdk.har로 배포되며 현재 HarmonyOS API 12 이상을 대상으로 합니다. HAR 패키지를 가져오고, 블루투스 권한을 요청하며, 스캔 콜백에서 반환되는 deviceId를 사용하여 연결합니다. 이 deviceId는 시스템 생성 개인 식별자일 수 있으며, address 필드는 표시용입니다. 비즈니스 결과는 DEVICE_DATA 이벤트를 통해 비동기적으로 반환됩니다.
프로토콜 구현 참고 사항
- 계층 구조: 애플리케이션/비즈니스 레이어 $\rightarrow$ SDK 코어 및 상태 머신(state machine) $\rightarrow$ 표준 BLE 프로토콜 $\rightarrow$
VendorAdapter $\rightarrow$ 장치 펌웨어.
- 참조 BLE GATT: 서비스
0xAE20, 쓰기 특성(write characteristic) AE21, 데이터 알림(data notification) AE22, 키 알림(key notification) AE23을 사용합니다.
- 일반 프레임:
MAGIC(0x5A) + SEQ + CRC-16/XMODEM + LEN + TYPE/CMD/PARAMS. 길이별로 버퍼링하고, 유효성을 검사하며, 중복을 제거하고, 재조립한 후, 요청과 응답 간의 상관관계를 분석합니다.
- 알림(Notifications)에는 패킷 전반에 걸쳐 부분 프레임, 다중 프레임 또는 노이즈가 포함될 수 있습니다. 데이터 및 키 알림은 독립적인 파서 버퍼를 사용하며, 송신자는 협상된 MTU(Maximum Transmission Unit)에 따라 프레임을 분할하고 순서를 유지합니다.
- 코어 명령어는 장치 정보, 배터리 및 용량, 녹음 상태, 파일 목록 및 다운로드, 시간 동기화, 키 응답, Wi-Fi 상태, 매개변수 설정 및 OTA(Over-The-Air) 상태를 다룹니다. 알 수 없는 명령어는 식별 가능한 오류를 반환해야 합니다.
- 파일 목록은
finish=1이거나 플랫폼 SDK가 완료를 보고할 때 완전한 것으로 간주합니다. 다운로드는 4바이트 리틀 엔디안(little-endian) offset을 사용하며, 애플리케이션은 파일 크기와 오디오 디코딩 가능 여부를 검증해야 합니다.
- 실시간 녹음 및 파일 콜백에는 원시 Opus 바이트가 포함됩니다. 기본 형식은 16kHz 모노, 프레임당 40바이트, 프레임당 20ms입니다. SDK는 Opus를 디코딩하거나 WAV 헤더를 생성하지 않습니다.
- OTA는 모드 및 환경 제어를 위해 BLE를 사용하고, 펌웨어 페이로드에는 Wi-Fi/TCP를 사용합니다. 업그레이드 전에 배터리, 버전, TCP 상태를 확인해야 하며, BLE 또는 Wi-Fi 중 하나라도 연결이 끊어지면 작업을 중지해야 합니다.
필드 정의, 명령어 테이블, 캡처된 프레임 및 호환성 규칙은 프로토콜 문서를 참조하십시오.
통합 체크리스트
- 실물 장치를 사용하여 데스크톱 데모를 실행하고 디스커버리(discovery), 연결(connection), 시간 동기화(time synchronization), 읽기 전용 확인(read-only check), 그리고 최소 하나의 파일 다운로드를 검증하십시오.
- 대상 플랫폼에 필요한 블루투스 권한을 요청합니다. SDK를 초기화하고, 디바이스 이벤트(device-event), 실시간 오디오(real-time-audio), 파일 데이터(file-data) 콜백을 등록한 다음, 디스커버리를 시작합니다.
- 스캔 콜백에서 반환된 식별자로 연결합니다. 연결 후에는 시간을 동기화하고 배터리, 용량(capacity), 펌웨어 버전, 파일 목록을 읽습니다.
- 콜백을 애플리케이션의 이벤트 큐 또는 상태 관리 계층으로 변환합니다. 메서드 호출은 요청이 제출되었음을 의미하며, 완료는 비동기 이벤트로 표현됩니다.
- 전용 디코더 작업에 40바이트 Opus 프레임을 전송합니다. 완료 이벤트에서 파일을 최종화하고, 오프셋을 기록하며, 사용자에게 표시하기 전에 크기와 디코드 가능성을 검증합니다.
- 오버 더 에어(OTA)는 Wi-Fi/TCP 연결이 되어 있고, 업데이트가 필요하며, 배터리가 최소 20퍼센트 이상일 때만 실행합니다. BLE 또는 Wi-Fi 연결이 끊어지면 업그레이드를 실패로 표시하고, 전체 펌웨어를 무작정 다시 전송하지 마십시오.
- 칩셋이나 모델을 추가할 때는 애플리케이션 코드에 공급업체(vendor) 비공개 필드를 노출하는 대신,
VendorAdapter, 기능 플래그(capability flags), 그리고 버전 협상(version negotiation)을 확장하십시오.
- 클라우드 ASR 키, 인증 코드, 실제 녹음 파일 또는 장치 식별자를 절대 하드코딩하거나 커밋하지 마십시오. 공유하기 전에 로그와 패킷 캡처를 검열(redact)하십시오.
사용 사례
이 프로젝트는 회의 녹음 및 메모 작성, 인터뷰, 교실 교육, 콘텐츠 제작, 검사 기록, 스마트 하드웨어를 위한 보조 앱, 기업 선물 및 홍보용 녹음기 등 여러 녹음기 칩셋을 하나의 애플리케이션에 통합해야 하는 기타 제품에 적합합니다.
하드웨어 적응 및 지원
하드웨어 통합은 일반적으로 다음 순서를 따릅니다: 기능 확인(confirm capabilities) → VendorAdapter 구현 → SDK 통합 → 실제 하드웨어에서 검증합니다. 하드웨어 팀은 칩셋 기능(chipset capabilities), BLE 서비스 및 특성(BLE services and characteristics), 비공개 명령어(private commands), 펌웨어 버전(firmware versions), 프로토콜 자료(protocol material), 그리고 테스트 시나리오를 제공해야 합니다. 어댑터는 이러한 차이점을 표준 인터페이스에 매핑하며, 애플리케이션 팀은 이후 Android, iOS, HarmonyOS 또는 Flutter API를 사용하여 제품 워크플로우를 구축합니다.
하드웨어 사양, 샘플 장치, HarmonyOS SDK, 전체 프로토콜 자료 또는 기술 지원이 필요하면 SoniCloud에 문의하십시오. 대상 플랫폼, 예상 물량, 장치 모델, 펌웨어 버전 및 의도된 사용 사례를 포함해야 합니다.
<img src="https://raw.githubusercontent.com/SonicloudTech/sonicloud_opensdk/HEAD/img/%E5%BE%AE%E4%BF%A1.png" alt="SoniCloud 연락처 QR 코드" width="200" style="max-width: 100%; height: auto;">
<br>
비즈니스 및 기술 문의: [email protected]
라이선스 및 사용 범위
예제 코드는 MIT 라이선스 하에 배포됩니다. AAR 파일, 정적 라이브러리(static libraries), HAR 패키지, 펌웨어, 장치 전용 프로토콜 및 일부 문서는 SoniCloud 또는 공급업체 소유의 자료를 포함할 수 있으며 반드시 오픈 소스는 아닙니다. 재배포 및 상업적 사용은 동봉된 패키지 약관 및 해당 적용 가능한 계약에 의해 규율됩니다.
인터페이스, 명령어 번호 및 동작은 현재 SDK, 펌웨어, 프로토콜 버전 및 실제 장치 검증 결과에 의해 정의됩니다. 이 SDK는 애플리케이션 측의 Opus 디코딩(Opus decoding), 파일 저장소(file storage), 권한 처리(permission handling) 또는 보안 제어 기능을 대체하지 않습니다. 승인 없이 비공개 프로토콜을 하드웨어 또는 제품과 함께 사용하지 마십시오.
관련 레포지토리
