AI 튜토리얼

AI 에이전트에 빠르고 검증된 비디오 컨텍스트 제공하기: CDAF 활용법

이 튜토리얼에서는 CDAF 설치, 타임스탬프가 포함된 사이드카 파일 생성, 원본 비디오와의 대조 검증, 텍스트의 AI 워크플로 통합 방법을 알아봅니다. 또한 일괄 처리, 세부 정보 프로필, 에이전트 스킬 설치, Python API 사용, 로컬 생성 옵션, 비디오 라이브러리를 효율적으로 검색하는 기법도 배울 수 있습니다.

2026년 8월 27일약 14분 소요

AI 에이전트에 빠르고 검증된 비디오 컨텍스트 제공하기: CDAF 활용법

CDAF의 기능

CDAF는 Cached Descriptive Asset Files의 약자로, 동영상을 위한 개방형 사이드카 형식입니다. 동일한 기본 이름을 사용해 타임스탬프가 포함된 일반 텍스트 설명을 동영상 옆에 저장합니다. 예를 들어 sunset-drone.mp4는 sunset-drone.cdaf와 함께 사용됩니다.

한 번 동영상을 설명한 뒤 이후 AI 작업에서 해당 설명을 재사용하는 것이 목적입니다. 매번 질문할 때마다 동일한 영상을 동영상 이해 모델에 보내는 대신, 에이전트는 훨씬 작은 CDAF 파일을 확인하고 읽을 수 있습니다.

footage/
sunset-drone.mp4
sunset-drone.cdaf

원본 동영상은 변경되지 않으며 일반 동영상 소프트웨어에서 그대로 재생할 수 있습니다. 사이드카는 UTF-8 텍스트로, 작은 메타데이터 헤더 뒤에 언어 모델에 맞게 최적화된 Markdown 설명이 이어지는 구조입니다.

사이드카를 안전하게 재사용할 수 있는 이유

CDAF 헤더에는 해당 동영상의 정확한 SHA-256 해시와 바이트 크기가 기록됩니다. 규격 준수 도구는 이 값을 사용해 설명이 여전히 유효한지 확인합니다. 동영상이 변경되면 사이드카는 오래된 상태가 되므로 사용해서는 안 됩니다.

--- CDAF/1.0
video: sunset-drone.mp4
sha256: 4a7d1ed4…
bytes: 48211394
duration: 00:00:31.500
generator: gemini-2.5-flash
created: 2026-08-26T14:03:12Z
---

## 요약
골든아워의 해안 고속도로를 촬영한 31초 분량의 항공 드론 영상…

## 구간
[00:00.0-00:05.2] 넓은 항공 전경으로 장면을 설정하는 숏…
[00:05.2-00:12.8] 드론이 앞으로 이동하며 하강한다…

## 음성 기록
(대사 없음)

## 화면 텍스트
(없음)

## 태그
drone, aerial, coastal highway, golden hour, sunset

본문에는 요약, 타임스탬프가 포함된 구간, 음성 기록, 화면 텍스트 및 태그를 제공할 수 있습니다. 규범적 형식, 최신성 의미, 버전 관리 규칙 및 섹션 문법은 프로젝트의 CDAF 1.0 사양을 참조하세요.

주요 기능

검증된 재사용: SHA-256 및 바이트 크기 메타데이터로 사이드카와 해당 사이드카가 설명하는 정확한 동영상을 연결합니다.
읽기 쉬운 텍스트 형식: 에이전트는 동영상을 다시 디코딩하지 않고도 설명을 사용하고, 검색하고, 재사용할 수 있습니다.
타임스탬프 구간: 구간 범위는 클립 선택과 편집 목록 생성에 활용할 수 있습니다.
종속성 없는 핵심 기능: 구문 분석, 직렬화, 해싱, 최신성 확인 및 구간 추출은 Python 표준 라이브러리를 사용합니다.
배치 지향 CLI: 명령줄 도구는 디렉터리의 사이드카를 생성하고 이미 최신인 항목은 건너뛸 수 있습니다.
여러 세부 수준 프로필: 생성 시 brief, standard, rich 출력을 지원합니다.
에이전트 스킬: 패키징된 스킬은 코딩 에이전트가 동영상을 분석하기 전에 검증된 사이드카를 확인하도록 안내합니다.
선택적 로컬 생성: 저장소에는 API 키 없이 로컬 모델로 생성할 수 있는 --local 제공자가 포함되어 있습니다.
선택적 탐색: CDAF는 ffprobe를 사용해 재생 시간, 해상도 및 프레임 레이트 메타데이터를 가져올 수 있으며, ffprobe를 사용할 수 없을 때도 기능을 유지하며 동작합니다.

에이전트 스킬 설치

지원되는 코딩 에이전트에 사이드카 우선 워크플로를 가르치는 가장 빠른 방법은 다음과 같습니다.

npx cdaf-skill

기본적으로 스킬은 ~/.claude/skills/cdaf에 설치되어 여러 프로젝트에서 사용할 수 있습니다. 지원되는 다른 설치 방식은 다음과 같습니다.

npx cdaf-skill --project
npx cdaf-skill --dir <path>
npx cdaf-skill --print

--project는 현재 프로젝트의 ./.claude/skills/cdaf에 설치합니다.
--dir은 지정한 디렉터리에 설치합니다.
--print는 스킬을 표준 출력에 기록하므로 다른 에이전트 프레임워크에 붙여 넣을 수 있습니다.

설치 프로그램을 다시 실행해도 안전합니다. 변경되지 않은 스킬은 그대로 두고, 수정된 스킬은 교체 전에 SKILL.md.bak으로 백업합니다.

동영상 파일을 분석하기 전에 동일한 기본 이름의 .cdaf 파일이 있는지 확인하세요. 해당 파일의 bytes 및 sha256 헤더 값이 동영상과 일치하면 동영상을 처리하는 대신 사이드카를 읽으세요.

CDAF CLI 설치

Python CLI에는 Python 3.10 이상이 필요합니다. PyPI 릴리스는 아직 계획 단계이므로 현재 README에서는 저장소에서 직접 설치합니다.

pip install "cdaf[generate] @ git+https://github.com/UditAkhourii/cdaf.git#subdirectory=cli"

복제한 저장소에서 작업 중이라면 로컬 cli 디렉터리에서 CLI를 설치하세요.

pip install ./cli[generate]

생성기 구현은 Gemini Files API를 사용합니다. Google AI Studio에서 Gemini API 키를 발급받은 다음 환경에 설정하세요.

macOS 및 Linux

export GEMINI_API_KEY=your-key

Windows PowerShell

$env:GEMINI_API_KEY="your-key"

영상 자료는 사용자가 보유한 API 키를 통해 처리됩니다. 기존 사이드카를 읽거나 검증만 하는 명령에는 API 키나 생성기 종속성이 필요하지 않습니다.

사이드카 생성

하나 이상의 동영상을 디렉터리에 넣고 해당 디렉터리를 대상으로 cdaf generate를 실행하세요.

cdaf generate ./footage

CDAF는 동영상을 설명하고 동일한 기본 이름의 사이드카를 생성합니다. 다시 실행하면 이미 최신 사이드카가 있는 동영상은 건너뜁니다.

세부 수준 프로필 선택

--detail을 사용해 문서화된 세 가지 생성 프로필 중 하나를 선택하세요.

cdaf generate ./footage --detail brief
cdaf generate ./footage --detail standard
cdaf generate ./footage --detail rich

다운스트림 작업에 필요한 설명적 맥락의 수준에 따라 프로필을 선택하세요. --model을 사용해 Gemini 모델을 선택하거나 --force로 재생성을 요청할 수도 있습니다.

cdaf generate ./footage --model <gemini-model>
cdaf generate ./footage --force

비디오 라이브러리 상태 확인

status 명령을 사용하면 사이드카를 FRESH, STALE 또는 MISSING으로 분류할 수 있습니다.

cdaf status ./footage

FRESH: 사이드카가 현재 비디오와 일치합니다.
STALE: 사이드카는 존재하지만 기록된 식별 정보가 더 이상 비디오와 일치하지 않습니다.
MISSING: 일치하는 CDAF 사이드카를 사용할 수 없습니다.

이 명령에는 API 키나 생성 종속성이 필요하지 않으므로 기존 에셋 라이브러리를 가볍게 점검하는 데 적합합니다.

검증된 설명 읽기

에이전트, 스크립트 또는 프롬프트에 사이드카 본문이 필요할 때는 cdaf read를 사용하세요.

cdaf read ./footage/sunset-drone.mp4

이 명령은 설명을 출력하기 전에 해시를 검증합니다. 오래된 사이드카의 출력은 거부하므로, 최신성 규칙을 에이전트 지침에만 의존하지 않고 도구 자체에서 적용할 수 있습니다.

자동화에서 사이드카 검증

검증 명령은 일치하는 사이드카가 올바른 형식이며 최신 상태일 때만 성공적으로 종료됩니다.

cdaf validate ./footage/clip.mp4

유효하고 최신인 사이드카에 대해서만 종료 상태 0을 반환하므로, 이 명령을 스크립트나 지속적 통합 워크플로에서 사용할 수 있습니다. 검증에는 API 키나 선택적 생성기 종속성이 필요하지 않습니다.

Python에서 CDAF 사용

핵심 Python API를 사용하면 애플리케이션이 사이드카를 찾고 불러온 후 검증하여 그 본문을 언어 모델에 전달할 수 있습니다.

from cdaf import load, check_freshness, sidecar_path_for

video = "footage/sunset-drone.mp4"
sidecar = load(sidecar_path_for(video))

if check_freshness(video, sidecar) == "fresh":
    context_for_llm = sidecar.body

이 패턴은 CDAF 통합의 핵심입니다. 예상되는 사이드카 경로를 계산하고, 파일을 파싱하며, 비디오를 기준으로 최신성을 검증한 뒤, 결과가 fresh일 때만 sidecar.body를 사용합니다.

패키지의 핵심 기능은 직렬화, 청크 단위 SHA-256 계산, 세그먼트 추출도 지원합니다. 이러한 작업에는 표준 라이브러리만 사용됩니다. 생성기별 코드는 생성이 요청된 경우에만 가져옵니다.

사이드카 우선 에이전트 워크플로 구축

편집, 검색 또는 질의응답 작업의 일부로 비디오 경로를 받습니다.
같은 기본 이름을 가진 .cdaf 파일을 찾습니다.
현재 비디오를 기준으로 사이드카의 최신성을 확인합니다.
최신 상태라면 다른 비디오 이해 작업을 실행하는 대신 텍스트를 읽습니다.
오래되었거나 없으면 내용을 신뢰하기 전에 재생성합니다.
요약, 세그먼트, 트랜스크립트, 화면 텍스트, 태그를 다운스트림 작업의 맥락으로 사용합니다.

패키지에 포함된 에이전트 스킬은 탐색 중에는 가벼운 크기 확인을 수행하고, 중요한 결정을 내릴 때는 전체 해시 확인을 수행하도록 제안합니다. 애플리케이션은 작업에 적합한 검증 수준을 사용하되, 오래된 설명을 신뢰해서는 안 된다는 핵심 규칙을 지켜야 합니다.

고급 팁

비디오 컬렉션을 텍스트로 검색

비디오에 사이드카가 생성되면 에이전트와 명령줄 도구는 모든 비디오를 여는 대신 .cdaf 파일을 검색할 수 있습니다. 태그와 설명을 활용하면 사람이 없는 해안의 일몰 장면과 같은 요청을 에셋 라이브러리에 대한 텍스트 검색으로 처리할 수 있습니다.

세그먼트를 편집 결정으로 변환

[00:05.2-00:12.8]과 같은 타임스탬프가 포함된 행은 프로그래밍 방식의 편집기가 클립이나 시퀀스로 변환할 수 있는 범위를 제공합니다. README는 이러한 구조의 이점을 얻을 수 있는 워크플로로 Remotion, HyperFrames, 프롬프트 기반 편집 도구를 명시하고 있습니다.

트랜스크립트 타이밍 재사용

음성이 포함된 경우 Transcript 섹션은 대화를 타임라인에 맞춰 정렬합니다. 편집 워크플로에서는 또 다른 이해 작업을 수행하는 대신 이 정보를 자막과 오디오 동기화에 재사용할 수 있습니다.

선택적 ffprobe 메타데이터 사용

ffprobe를 사용할 수 있으면 CDAF의 probe 구성 요소가 재생 시간, 해상도, 초당 프레임 수 메타데이터를 수집할 수 있습니다. ffprobe가 없어도 엔진은 정상적으로 계속 작동하므로, 이 선택적 통합이 기본 사이드카 작업을 차단하지 않습니다.

로컬 생성 고려

저장소에는 --local을 통해 제공되는 로컬 프로바이더가 포함되어 있습니다. API 키를 사용하지 않고 로컬 모델로 생성하려는 경우를 위한 기능입니다. 현재 지원되는 로컬 모델 설정은 저장소의 로컬 프로바이더 구현을 참조하세요.

백엔드와 형식 분리

CDAF 자체는 모델에 종속되지 않습니다. Gemini는 포함된 원격 생성기 백엔드이며, 다른 비디오 언어 모델 백엔드도 동일한 Sidecar 유형 뒤에 연결할 수 있습니다. 추가 Claude, GPT 및 로컬 VLM 백엔드는 로드맵에 올라와 있으므로 아직 사용할 수 있다고 가정해서는 안 됩니다.

벤치마크 재현

저장소에는 ffmpeg를 사용해 스크립트 레시피에서 비디오를 합성하는 객관적인 벤치마크가 포함되어 있습니다. 다음 단계를 순서대로 실행하세요.

python benchmarks/bench.py make
python benchmarks/bench.py run
python benchmarks/bench.py report

첫 번째 단계에는 ffmpeg가 필요하고, 두 번째 단계에는 GEMINI_API_KEY가 필요하며, 마지막 단계에서는 benchmarks/RESULTS.md 파일을 작성합니다. 보고된 20개 질문 테스트에서 사이드카 답변은 직접 동영상을 사용한 경우의 20개 중 19개 정답보다 높은 20개 중 20개의 정답을 기록했으며, 질문당 평균 프롬프트 토큰도 3,066개가 아닌 303개를 사용했습니다. 이는 저장소의 벤치마크 결과이며, 영상, 모델, 프롬프트 및 환경에 따라 달라질 수 있습니다.

현재 제한 사항 및 로드맵

README에는 PyPI 릴리스, MCP 서버, 호스팅된 변환기, 추가 생성기 백엔드, Node 또는 TypeScript 엔진 포트, 자연 영상 벤치마크 확장, 서명된 사이드카 등 여러 항목이 현재 기능이 아닌 향후 작업으로 명시되어 있습니다. 이러한 로드맵 구성 요소를 사용할 수 있다고 가정하지 말고, 지금은 문서화된 Git 기반 Python 설치 방법과 기존 CLI를 사용하세요.

결론

CDAF는 반복적인 동영상 분석을 검증 후 읽기 workflow로 변환합니다. 사이드카를 한 번 생성하고 원본 동영상 옆에 보관한 다음, 에셋을 사용할 때마다 검증하고 그 본문을 다운스트림 에이전트에 제공하세요. 형식에 포함된 해시는 편집 후 실수로 재사용하는 것을 방지하며, 요약, 타임스탬프, 트랜스크립트, 텍스트 및 태그를 통해 동영상 라이브러리를 더 쉽게 검색하고 자동화할 수 있습니다.

CDAF는 MIT 라이선스로 제공됩니다. 소스 코드, 사양, 예제, 벤치마크 세부 정보 및 에이전트 스킬은 CDAF GitHub 저장소에서 확인할 수 있습니다.