← 가이드로 돌아가기
PrivateFrame로컬 동영상 처리데스크톱 · CLI · Python흐림 및 모자이크

PrivateFrame — 설치 및 사용 가이드

데스크톱 앱으로 시작하거나, 동영상 작업을 자동화하거나, Python에 처리 기능을 통합하세요.

•읽는 데 8분

이 가이드에서 구축할 내용

내 기기에서 동영상의 얼굴을 감지하고 추적한 뒤 흐림이나 모자이크를 적용하세요. 모든 얼굴을 처리하거나 참조 사진으로 얼굴을 그대로 보여줄 사람을 선택할 수 있습니다.

InsightFace 사전 학습 모델을 상업적으로 배포하려면 별도의 상업용 모델 라이선스가 필요합니다.

동영상 데모

PrivateFrame의 실제 결과를 확인하세요.

다양한 장면에서 얼굴을 추적하고 가리는 모습과 가우시안 흐림 및 모자이크 결과를 확인하세요.

PrivateFrame의 실제 출력 결과입니다. 공유하기 전에 처리된 동영상을 검토하세요.

동영상 열기

음악: Scott Buckley의 Tears in Rain · CC BY 4.0. 일부 발췌 및 믹싱.

시작하기 전에

  • Python 3.10 이상과 python-package/insightface/app/privateframe/을 포함하는 최신 InsightFace 소스가 필요합니다. 해당 저장소의 루트에서 설치 명령을 실행하세요. 이 가이드는 최신 소스 패키지를 사용하며, 이전 저장소나 배포된 패키지에는 PrivateFrame이 아직 포함되지 않았을 수 있습니다.
  • 로컬 영상과 출력 폴더를 준비하세요. 예제의 /data/... 경로를 기기의 경로로 바꾸세요. 각 예제에서 다른 출력 폴더를 사용하면 결과를 별도로 보관할 수 있습니다.
  • 의존성과 모델을 설치하면 동영상 처리는 로컬에서 실행됩니다. 처리를 위해 동영상이나 참조 사진을 업로드하지 않습니다. 처음 사용할 때 없는 모델을 다운로드할 수 있습니다.

1. 설치 및 사용 가이드

Python 3.10 이상과 python-package/insightface/app/privateframe/을 포함하는 최신 InsightFace 소스가 필요합니다. 해당 저장소의 루트에서 설치 명령을 실행하세요. 이 가이드는 최신 소스 패키지를 사용하며, 이전 저장소나 배포된 패키지에는 PrivateFrame이 아직 포함되지 않았을 수 있습니다.

Python 3.10 이상이 필요합니다. 가이드에 따라 업데이트된 저장소에서 설치하세요. 처음 실행할 때 모델 다운로드가 필요할 수 있습니다. 제공되는 사전 학습 모델은 비상업적 연구 평가 전용입니다. 상업적으로 배포하기 전에 모델 라이선스를 취득하세요.

데스크톱 앱
python -m pip install "./python-package[gui]"
명령줄 / Python API
python -m pip install "./python-package[privateframe]"
insightface-privateframe --help

2. 데스크톱 앱

InsightFace Evaluation Studio에서 PrivateFrame을 열고 동영상, 설정, 출력 폴더를 선택하세요.

  • InsightFace 데스크톱 앱에서 PrivateFrame을 열거나 CLI 또는 Python API에 동영상을 전달하세요.
  • 선택 모드를 정하고 필요하면 참조 사진을 추가한 다음, 흐림 또는 모자이크를 선택하세요.
  • 새 동영상과 재사용 가능한 분석 JSON을 내보내세요. 공유하기 전에 결과를 검토하세요.
데스크톱 앱
insightface-gui

3. 명령줄 — 가릴 사람 선택

명령 하나로 동영상을 처리하거나 분석과 렌더링을 분리해 검토 및 반복 내보내기를 할 수 있습니다.

사진을 사용하는 모드에서는 한 사람이 선명하게 나온 JPG, JPEG, PNG, WebP 사진을 하나의 참조 폴더 바로 아래에 넣으세요. 각 사진에서는 가장 크게 검출된 얼굴만 사용합니다. 두 사진 모드 모두 사용 가능한 참조 얼굴이 하나 이상 필요합니다. 기본 정책에서 일치하지 않거나 불확실한 얼굴은 blur_only에서 보이고 exempt에서는 흐리게 처리됩니다.

  • 모든 얼굴 가리기: 감지된 모든 얼굴을 가립니다. 참조 사진이나 신원 매칭이 필요하지 않습니다.
  • 선택한 사람만 가리기: 참조 사진과 일치하는 사람의 얼굴을 가리고 다른 사람의 얼굴은 그대로 보여줍니다.
  • 선택한 사람만 그대로 보여주기: 일치하는 사람의 얼굴은 그대로 보여주고, 일치하지 않거나 매칭이 불확실한 얼굴은 가립니다.
모든 얼굴 가리기
insightface-privateframe process \
  --input /data/video.mp4 --output-dir /data/all
선택한 사람만 가리기
insightface-privateframe process \
  --input /data/video.mp4 --output-dir /data/selected \
  --recognition.mode blur_only \
  --recognition.reference_dir /data/reference_photos
선택한 사람만 그대로 보여주기
insightface-privateframe process \
  --input /data/video.mp4 --output-dir /data/exempt \
  --recognition.mode exempt \
  --recognition.reference_dir /data/reference_photos

4. 한 번 분석하고 여러 번 렌더링

분석 JSON을 재사용하여 렌더링 설정이나 얼굴 상자를 수정하세요. 감지와 인식을 반복할 필요가 없습니다.

네. 원본 동영상과 분석 JSON을 보관하면 흐림, 모자이크, 인코딩 설정을 바꿔 다시 렌더링할 수 있습니다. JSON의 얼굴 상자도 수정할 수 있습니다. 감지 또는 신원 매칭 설정을 변경하려면 새로 분석해야 합니다.

analyze
insightface-privateframe analyze \
  --input /data/video.mp4 --output-dir /data/review
render · mosaic
insightface-privateframe render \
  --input /data/video.mp4 \
  --result /data/review/video_privateframe.json \
  --redacted /data/review/video_mosaic.mp4 \
  --render.redaction.method mosaic

5. Python API

진행률 및 취소 콜백을 사용하면서 분석과 렌더링을 자체 애플리케이션에 통합하세요.

Python API
from insightface.app.privateframe import (
    analyze_streaming_pipeline,
    default_output_paths,
    render_streaming_artifacts,
)
from insightface.app.privateframe.base_config import DEFAULT_CONFIG_PATH

paths = default_output_paths("/data/video.mp4", "/data/python_output")

analysis = analyze_streaming_pipeline(
    config_path=DEFAULT_CONFIG_PATH,
    input_path=paths.source,
    workdir=paths.workdir,
    result_path=paths.result_json,
)

rendered = render_streaming_artifacts(
    input_path=paths.source,
    result_path=paths.result_json,
    redacted_path=paths.result_video,
    config_overrides={"render.redaction.method": "mosaic"},
)

6. 처리하고, 검토하고, 공유

새 동영상과 재사용 가능한 분석 JSON을 내보내세요. 공유하기 전에 결과를 검토하세요.

사진 매칭 과정에서 사람을 놓칠 수 있습니다. 공유하기 전에 선택적 처리 결과를 검토하세요. 선택한 사람만 가리는 모드에서는 매칭되지 않은 대상 인물의 얼굴이 그대로 보일 수 있습니다.

아니요. 감지, 추적, 매칭 과정에서 얼굴을 놓치거나 오류가 발생할 수 있습니다. 특히 짧게 등장하는 얼굴, 장면 전환, 가려진 얼굴에 주의하여 내보낸 동영상을 검토하세요. 얼굴 가리기는 목소리, 이름, 옷차림이나 신원을 식별할 수 있는 다른 맥락 정보를 숨기지 않습니다.

7. PrivateFrame을 상업적으로 사용할 수 있나요?

InsightFace 코드는 MIT 라이선스로 제공됩니다. 프로젝트에서 제공하는 사전 학습 모델은 비상업적 연구용이며, 상업적 사용에는 적절한 모델 사용 허가가 필요합니다. 배포에 관해 문의해 주세요.

동영상 얼굴 개인정보 보호를 작업에 더하세요.

InsightFace 사전 학습 모델을 상업적으로 배포하려면 별도의 모델 라이선스가 필요합니다. 코드는 MIT 라이선스로 제공되며, 코드와 모델에는 각각의 라이선스가 적용됩니다.

상업용 라이선스 신청