Take a photo. Change one thing.

adb version이 실패하면 Android SDK Platform-Tools의 실행 파일을 전체 경로로 호출하거나 PATH에 추가합니다.

• Windows는 PowerShell·CMD에서 실행합니다.

  Git Bash는 먼저 export MSYS2_ARG_CONV_EXCL='*' MSYS_NO_PATHCONV=1을 설정해야 기기 경로가 Windows 경로로 바뀌지 않습니다.

• WSL은 Linux adb로 무선·USB 연결을 사용하거나 Windows adb.exe를 호출합니다.

  Windows 실행 파일로 pull하면 C:/Users/USERNAME/Downloads 같은 Windows 대상 경로를 씁니다. 실행·조회·회수에 같은 ADB 실행 파일을 유지합니다.

• 무선 연결은 adb pair IP:PAIR_PORT 후 adb connect IP:PORT입니다.

  주소·코드는 기기의 무선 디버깅 화면에서 확인하며 두 포트는 다를 수 있습니다. 같은 기기의 USB·무선 연결도 별도로 선택합니다.

WSL에서 Windows ADB를 호출하려면 사용자명과 SDK 경로를 바꿉니다.

adb() { "/mnt/c/Users/USERNAME/AppData/Local/Android/Sdk/platform-tools/adb.exe" "$@"; }
adb devices -l

영상 10초를 저장하세요

1. 무음 녹화를 시작합니다. 소리가 필요하면 --no-audio를 빼고 앱에서 마이크 권한을 허용하세요.

   adb shell sh /data/local/tmp/halcam record start --camera 0 --no-audio
   

2. Recording started가 표시된 뒤 10초를 촬영하고 종료합니다. record stop은 MP4 저장 완료까지 기다립니다.

   adb shell sh /data/local/tmp/halcam record stop
   

출력된 adb pull 명령으로 받은 MP4를 재생하세요. record start의 성공은 녹화 시작이고 파일 저장 완료는 아닙니다.

녹화 중 사진도 필요하면 종료 전에 record snapshot을 실행합니다. 저장 중 종료를 요청해도 사진 저장을 기다리며 MP4와 사진을 함께 받습니다.

스냅샷 지원은 엔진·출력 구성에 따라 다릅니다. 화면에서 시작한 녹화는 CLI로 멈추지 않습니다.

사진의 차이를 비교하세요

• 카메라 JPEG와 앱 변환 JPEG를 비교합니다.

  capture --camera 0 --jpeg-size yuv

  YUV에서 만든 JPEG와 촬영 JSON을 확인합니다. 원본 YUV 파일을 지정하는 옵션은 아닙니다.

• 움직이는 피사체를 세 번 찍습니다.

  burst --camera 0 --count 3 --interval-ms 500

  저장한 장수와 목표 장수를 비교합니다.

• 서로 다른 노출로 찍습니다.

  bracket --camera 0

  AEB 원본과 가능한 HDR을 확인합니다. HDR을 만들지 못하면 생략 이유를 읽습니다.

• RAW를 저장합니다.

  capture --camera 0 --yuv-size off --jpeg-size off --raw-size WIDTHxHEIGHT

  streams에서 고른 크기의 DNG를 확인합니다. Camera2와 RAW 지원이 필요합니다.

출력 크기나 수동 설정을 바꾸려면 지원 조건을 먼저 확인하세요.

PIP로 한 장과 원본을 비교하세요

PIP 사진은 합성 사진과 두 카메라의 원본을 비교할 수 있습니다. 영상은 합성 MP4를 저장합니다.

1. 원하는 카메라·엔진·모드로 프리뷰를 열고 후보를 조회합니다. 영상이라면 첫 명령에 --mode Video를 붙입니다.

   adb shell sh /data/local/tmp/halcam preview --camera 0
   adb shell sh /data/local/tmp/halcam pip sources
   

2. selectable: true인 후보의 type과 ID를 사용합니다. 아래는 Service 후보를 선택한 예시이며 ID는 조회 값으로 바꿉니다.

   adb shell sh /data/local/tmp/halcam capture --camera 0 --pip-type service --pip-camera ID
   

조회와 촬영의 카메라·엔진을 맞추세요. Not verified 후보는 실제 구성에서 실패할 수 있습니다.

스트림 크기를 지정하세요

조회와 실행에 같은 카메라·엔진·모드를 사용하세요. 기본 엔진은 Camera2이며 CameraX는 양쪽 명령에 --engine CameraX를 붙입니다.

adb shell sh /data/local/tmp/halcam streams --camera 0 --mode Video
adb shell sh /data/local/tmp/halcam preview --camera 0 --mode Video --video-size 1280x720 --video-fps 30

프리뷰 준비만으로 녹화가 시작되지는 않습니다.

Photo 모드에서는 다음 설정을 사용합니다.

• 촬영: capture·burst·bracket은 Photo입니다.
• 프리뷰·지원 조회: preview·streams의 기본 모드입니다.
• 출력·FPS: --jpeg-size, --raw-size, --fps를 사용합니다.
• 손떨림 보정: Off이며 AUTO도 Off로 적용됩니다.

Video 모드에서는 다음 설정을 사용합니다.

• 녹화: record start는 Video입니다.
• 프리뷰·지원 조회: preview·streams에 --mode Video를 붙입니다.
• 출력·FPS: --video-size, --video-fps, --codec을 사용합니다.
• 손떨림 보정: --stabilization의 지원 값은 streams에서 확인합니다.

새 카메라 명령은 기본값과 명시한 옵션으로 구성합니다. 이전 UI·CLI 설정과 PIP를 이어받지 않습니다.

모드에 맞지 않거나 지원하지 않는 옵션은 PREFLIGHT_FAILED로 거부하며 다른 크기로 자동 변경하지 않습니다.

지원 목록은 개별 크기·인코더 조건입니다. 출력 조합의 성공까지 보장하지 않으므로 실제 세션 구성에서 실패할 수 있습니다.

적용된 값은 프리뷰·녹화 결과의 result.streams에서 확인합니다.

벤치마크를 실행하세요

adb shell sh /data/local/tmp/halcam benchmark run --camera 0

앱과 같은 camera2-standard-v2 프로파일로 측정하고 원본 JSON을 받습니다.

보고서 저장 성공과 측정·비교 가능 여부는 별개입니다. 원본 JSON의 validity를 확인하세요. 비교 판정은 저장된 측정값으로 다시 계산합니다.

프로파일은 고정이며 --engine, Live 스트림, --no-audio를 받지 않습니다. 크기를 자동 대체하거나 baseline을 자동 지정하지 않습니다.

보고서에는 이미지 픽셀·녹화 MP4가 포함되지 않습니다.

adb shell "sh /data/local/tmp/halcam benchmark run --camera 0 --build 'Candidate A' --note 'Same room'"

CTS와 다른 작업을 찾으세요

CTS는 아래 목록에서 나온 키를 그대로 사용합니다.

adb shell sh /data/local/tmp/halcam cts cases
adb shell sh /data/local/tmp/halcam cts run --cases custom:fast_on_off

여러 키는 쉼표로 구분합니다. 결과 보고서의 passed·failed와 CLI 실행 상태를 구분해 확인하세요.

사양만 필요하면 probe로 카메라를 열지 않고 JSON·TXT를 받습니다.

status는 앱 상태를, status REQUEST_ID는 그 요청을 읽습니다.

셸의 status --last와 ID 없는 fetch·cancel은 마지막 제출 요청을 사용합니다. 다른 작업과 혼동하지 않도록 복구에는 ID를 명시합니다.

requests list는 요청을 새로 제출하지 않는 조회입니다. 다른 작업이 실행 중이어도 동작하고, 보관 중인 기록을 밀어내지 않습니다.

기기의 Download/HALCamera-cli/요청ID에는 크기·SHA-256을 검증한 복사본이 준비됩니다.

바이너리는 PC 셸의 > 대신 adb pull로 받습니다. PC 파일도 아래 manifest의 크기·해시와 대조합니다.

adb exec-out content read --uri content://dev.halcamera.cli/v1/requests/REQUEST_ID/files

manifest는 파일 ID·이름·바이트 수·SHA-256을 탭으로 구분합니다.

• PowerShell: (Get-Item -LiteralPath 'FILE').Length와 Get-FileHash -LiteralPath 'FILE' -Algorithm SHA256을 사용할 수 있습니다.
• Linux·WSL: wc -c와 sha256sum을 사용할 수 있습니다.

완료 기록은 최대 24시간·200개입니다.

만료 시각부터 요청·파일 조회는 실패하지만 원본 사진·영상과 회수용 복사본은 삭제하지 않습니다. 필요한 파일은 실행 직후 받으세요.

기본 실행 제한은 작업마다 다릅니다.

• 사진·프리뷰·probe: 30초입니다.
• benchmark: 600초입니다.
• CTS: 1,800초입니다.
• 녹화: 3,600초입니다.

--timeout 초는 앱 작업의 제한이며 1–3,600초로 지정합니다. 녹화가 제한에 도달하면 종료하고 시간 제한 오류를 기록합니다.

녹화 준비에는 최대 30초를 기다립니다.

• NOT_RECORDING: CLI 녹화가 시작됐는지 요청 상태를 확인합니다.
• APP_NOT_FOREGROUND: Live 화면을 열어야 하며 스크립트는 이를 자동 처리합니다.

준비·측정 중에는 기기 화면을 조작하지 마세요. CLI는 Android 사용자 0을 대상으로 합니다.

이 영역의 halcam은 PC 명령이며 ADB 접두어를 붙이지 않습니다. 저장소와 Python 3.11 이상이 있는 환경에서 설치합니다.

APK만 받았다면 앞의 ADB 스크립트로 실행할 수 있습니다.

python -m pip install ./tools/halcam
halcam --serial SERIAL doctor --json
halcam --serial SERIAL capture --camera 0 --output ./photos --json
halcam --serial SERIAL record start --no-audio
halcam --serial SERIAL record stop --output ./videos

인자 없는 halcam은 시작 안내, halcam --help는 전체 문법을 보여 줍니다.

• --json: stdout에 JSON 하나를 출력합니다.
• --output: PC에서 파일의 크기·SHA-256을 검증해 저장합니다.
• --wait-timeout: PC 대기만 제한합니다.

--no-wait로 제출했거나 PC 대기가 먼저 끝났다면 같은 요청을 다시 기다립니다.

wait는 완료될 때까지 상태를 조회하고, --output을 주면 완료 뒤 파일을 받습니다.

요청을 다시 제출하지 않으며 Ctrl+C로 멈춰도 앱 작업을 취소하지 않습니다. ID를 잃었으면 halcam requests로 먼저 찾습니다.

halcam --serial SERIAL requests
halcam --serial SERIAL wait REQUEST_ID --output ./photos

녹화 요청은 record stop이 와야 끝나므로 wait 대신 record stop --output DIRECTORY를 사용합니다.

일반 촬영 옵션과 공통 run 문법은 halcam --help와 doctor --json에서 확인하세요. 이전 control record.stop은 저장 완료를 기다리지 않으므로 record stop --output DIRECTORY를 사용합니다.

스크립트 없이 호출하면 접수 결과만 반환합니다. Live 작업 전에 화면을 열고 request_id로 완료를 조회합니다.

adb shell am start -W -n dev.halcamera/.cli.CliLaunchActivity
adb shell content call --uri content://dev.halcamera.cli --method capture --extra camera:s:0
adb exec-out content read --uri content://dev.halcamera.cli/v1/requests/REQUEST_ID

직접 호출의 작업·인자·완료 규칙은 CLI 스킬과 APK의 /v1/hello 계약을 따르세요. content call은 접수만 반환하므로 반드시 ID로 완료를 조회합니다.