콘텐츠로 이동

개발 환경

개발 워크플로는 의존성 관리에 uv 를 사용하고, 스트리밍 레코더용 시스템 GStreamer 설치 (macOS only).

사전 요구사항

  • Python 3.13 (3.11+면 동작, 3.13이 빌드 타깃).
  • uv. macOS는 Homebrew: brew install uv. 또는 standalone installer.
  • macOS only: 시스템 전역 GStreamer.framework 설치 (gstreamer.freedesktop.org에서 다운로드). 런타임 그리고 development 패키지 둘 다.
  • Git — submodule 지원 포함.

클론 + 서브모듈

git clone https://github.com/cloneisyou/cue.git
cd cue
git submodule update --init --recursive

서브모듈 (vendor/ocap-macos, vendor/ocap-windows, vendor/open-world-agents-private)은 레코더 파이프라인에 필요. 서브모듈 / 벤더링에서 각 역할 참고.

macOS: GStreamer + PKG_CONFIG_PATH

PyGObject (ocap을 통해 transitive)가 GStreamer.framework 헤더를 찾으려면 pkg-config 필요. uv pip install 실행 전에 설정:

export PKG_CONFIG_PATH="/Library/Frameworks/GStreamer.framework/Versions/1.0/lib/pkgconfig"

이거 빠뜨리면 pygobject 빌드가 "package gobject-introspection-1.0 was not found" 에러로 실패.

miniforge / conda 셸에서 실행 금지

이게 macOS dev 머신에서 가장 흔한 실패 패턴.

Miniforge / conda 환경이 자체 GStreamer / GLib dylib을 DYLD_LIBRARY_PATH에 주입. Cue 프로세스가 그런 셸에서 시작하면 그 dylib들이 GStreamer.framework의 것보다 먼저 로드되고, GStreamer 파이프라인 파싱이 미묘한 심볼 불일치로 크래시.

해결: miniforge activation 없는 새 터미널 윈도우 열기, 또는 conda deactivate 명시적으로 — 프롬프트에 (base) / (env) prefix 없을 때까지.

non-conda Python으로 인터프리터를 핀하는 안전한 uv venv:

uv venv --python /opt/homebrew/opt/python@3.13/bin/python3.13

또는 그냥 Homebrew의 python3 직접:

brew install python@3.13
uv venv --python python3.13

설치

# macOS
uv pip install -e ".[macos]"

# Windows
uv pip install -e ".[windows]"

로컬 디지스트 백엔드 의존성도 미리 설치하고 싶으면 ,on-device 추가:

uv pip install -e ".[macos,on-device]"

on-device extra가 재개 가능 Gemma 4 가중치 다운로드용 huggingface_hub 가져옴. 번들된 llama-server 바이너리는 첫 빌드 시 빌드 스크립트 (scripts/build_nuitka.sh)가 다운로드.

실행

uv run python -m cue

메뉴바 (macOS) 또는 시스템 트레이 (Windows)에 ◈ 아이콘 출현. 첫 실행 시 API 키 프롬프트 — Anthropic 키 paste.

테스트

uv pip install -e ".[macos,dev]"   # pytest 추가
uv run pytest -q

테스트 스위트 커버: PII recognizer, 디지스트 출력 scrub, 프레임 선택, 이미지 전처리, llama-server contract, 로컬 모델 매니페스트, 설정 모델. 디지스트 품질 평가 harness는 평가 / 스모크 참고 (단위 테스트와 별개).

Lint + format

uv run ruff check src/ tests/
uv run ruff format src/ tests/

CI가 push / PR에 실행. Vendor 서브모듈은 ruff에서 제외.

흔한 함정

  • pygobject install 실패 — PKG_CONFIG_PATH가 install 전 미설정. pkg-config --list-all | grep gstreamer로 framework가 보이는지 확인.
  • macOS에서 스트리밍 레코더가 rc=-11 (SIGSEGV)로 죽음 — conda dylib 오염. 위 "miniforge / conda 셸에서 실행 금지" 참고.
  • 핫키가 동작 안 함 — 인터프리터에 Accessibility 권한 미부여. 트러블슈팅 참고.

다음