자동화 튜토리얼 비디오 스튜디오
웹사이트 주소나 소프트웨어 이름과 대략적인 챕터 순서가 주어지면, 이 스킬이 담당합니다:
실제 조작 수행 → 사용자에게 녹화 알림 → 수집된 자료 가져오기 → 검색 가능한 인덱스 구축 → 문장 단위 대응 편집 → 모션 효과 및 전환 → 프레임 단위 검증 → 완성본
역할 분담: 스킬이 하는 일, 사용자가 하는 일
| 담당 | 설명 | |
|---|---|---|
| 화면 녹화 | 사용자 | 사용자가 OBS / ShareX / 시스템 녹화 등의 외부 도구로 녹화하며, 스킬은 녹화하지 않습니다. 외부 녹화는 원본 해상도와 선명도를 유지하고 시스템 사운드도 녹음할 수 있습니다 |
| 실제 조작 | 스킬 | 스킬이 브라우저 CDP 또는 윈도우 자동화로 각 단계를 수행하고 조작 위치를 기록합니다 |
| 편집, 음성, 모션 효과, 검증 | 스킬 | 모두 자동화되며 게이트가 있습니다 |
| 자료 등록 | 사용자 | 조작이 끝나면 녹화된 비디오를 스킬에 제공합니다(경로만 알려주면 됩니다) |
스킬은 사용자의 하드웨어 마우스를 점유하지 않습니다: 브라우저 조작은 CDP 요소 클릭을 사용하며 실제 포인터를 움직이지 않습니다.
일곱 가지 철칙
- 수집은 사용자, 스킬은 녹화하지 않습니다. 스킬은 조작과 후반 작업만 담당합니다. 사용자가 녹화를 마치면 반드시 파일을 스킬에 제공해야 합니다.
- 조작은 스킬, 녹화 창은 사용자. 스킬은 사용자가 '녹화 시작'을 알린 후에야 조작을 시작하고, 조작이 끝나면 즉시 사용자에게 녹화 중지를 알립니다.
- 녹화 중 화면에 제어판이 보이면 안 됩니다. 스킬의 모든 명령은 창 없이 실행되어야 하며,
guard를 켜서 새로 뜨는 제어판과 오버레이를 즉시 숨깁니다. 이는 모두 녹화에 포함되기 때문입니다. - 창을 숨기기만 하고, 닫지는 않습니다.
SW_HIDE를 사용하고,guard stop으로 일괄 복원합니다. - 각 샷은 하나의 음성 대사에 연결됩니다.
plan.json의 각 비트(beat)는 몇 번째 음성 대사를 위한 것인지 선언하며, 챕터의 총 길이는 해당 챕터 음성 대사의 총 길이와 같아야 합니다. - 언급된 숫자는 실제 인터페이스에서 읽어야 합니다. 정점 수, 가격, 버전 번호 등은 모두 인터페이스를 기준으로 합니다.
- 가림 감사는 게이트이지, 보고서가 아닙니다. 빌드 전에 프레임 단위 OCR로 출력 창을 검사하여 제어판/알림/시작 페이지가 발견되면 출력을 거부합니다. BGM은 음성에 양보해야 하며, 완성본은 −16 LUFS, 트루 피크 ≤ −1.5 dBFS여야 합니다.
단계 0 · 프로젝트 수립
세 가지 사항을 확인해야 하며, 하나라도 없으면 안 됩니다:
- 대상: 웹사이트 주소 또는 데스크탑 소프트웨어 이름, 버전.
- 개요: 챕터 순서(사용자가 대략적으로 제공하면 되며, 세부 사항은 스킬이 보충합니다).
- 녹화 계획: 사용자가 사용할 녹화 도구, 녹화할 디스플레이 영역, 시스템 사운드 녹음 여부, 출력 형식 및 해상도.
동시에 수집 범위(전체 화면인지 특정 창인지)와 분할 녹화 여부를 결정합니다. 기능별로 하나씩 여러 번 녹화하는 것이 가장 유지보수에 좋고; 한 번에 전체 흐름을 녹화할 수도 있지만, 인덱스를 통해 위치를 찾아야 합니다.
단계 1 · 대본 작성
build/script.md, 각 챕터는 ## 제목으로 시작하며, 형식은 ## <챕터 ID> | <표시 제목>입니다:
## ch00 | 시작
먼저 제가 만든 결과물을 보여드립니다.
이 피규어는 한 장의 이미지로 생성되었습니다.
## ch01 | 회원가입 및 로그인
공식 웹사이트는 hi3d.ai이며, 브라우저에서 열면 바로 사용할 수 있습니다.
- 챕터 ID는 소문자, 숫자, 밑줄, 하이픈만 사용 가능하며(TTS 목록 요구사항),
plan.json의 챕터id와 완전히 일치해야 합니다. 동일 챕터의 여러 세그먼트는 자동으로ch01,ch01_1,ch01_2로 구성됩니다. - 표시 제목은 챕터 카드용이며, 한글이나 기타 언어로 쓸 수 있습니다.
- 챕터 ID가 서로의 접두사가 되지 않도록 주의하세요(
ch0와ch01이 혼동될 수 있음).chNN형식을 통일하는 것이 좋습니다. - 시작 부분은 먼저 결과물(가장 인식하기 쉬운 화면)을 보여준 후, 조작으로 돌아갑니다.
- 주변 기능은 한 문장으로 간략히 다루고, 분량은 '결과를 결정짓는 몇 가지 매개변수'와 '올바르게 수행되었는지 확인하는 방법'에 할애합니다.
- 프롬프트, 코드, 설정은 ``` 펜스 코드 블록으로 저장하세요. 코드 블록은 읽히지 않으며, 화면으로만 표시됩니다.
- 각 음성 대사에는 대응하는 실제 화면이 있어야 합니다. 당장 화면이 없는 단락은 화면으로 증명할 수 있는 문장으로 다시 작성하세요.
단계 2 · 음성 합성
python scripts/studio.py voice --project <프로젝트>
## <챕터 ID> | <제목>을 기준으로 챕터를 나누고, 빈 줄로 문장을 구분하며, 코드 블록과 > 주석은 건너뛰고, build/audio_map.json을 생성합니다. 각 세그먼트에는 실제 측정된 길이가 포함됩니다.
출력의 chars/s를 확인하세요: 3.0 미만인 단락은 TTS 이상(특정 합성이 길어짐)이므로, 다시 작성한 후 재생성하고, 그대로 편집에 사용하지 마세요.
단계 3 · 실제 조작 및 외부 녹화 ★
이것이 이 스킬의 핵심 단계입니다.
3.1 녹화 환경 준비
python scripts/studio.py windows # 대상 창 찾기
python scripts/studio.py prep --project <프로젝트> \
--keep-title "Chrome" --maximize-title "Chrome" # 관련 없는 창 숨기기, 대상 창 최대화
prep는 스킬 자신의 터미널을 절대 숨기지 않습니다(조상 PID 기준으로 제외).
3.2 화면 가드 시작 ★
이 단계는 생략할 수 없습니다. 스킬이 조작 과정에서 명령어(ffmpeg, ffprobe, python 서브 프로세스)를 실행할 때마다 제어판 창이 뜰 수 있으며, 이는 사용자의 수집 화면에 나타나 녹화될 수 있습니다.
python scripts/studio.py guard start --project <프로젝트> \
--protect "DeepSeek Harness" --protect "Chrome"
가드는 독립적인 백그라운드 프로세스로, 0.25초마다 창 목록을 스캔하여 새로 나타난 제어판 클래스 창(ConsoleWindowClass, cmd, PowerShell, 터미널, xshell 등)과 입력기/알림 오버레이를
즉시 SW_HIDE 처리합니다. 숨긴 창을 기억했다가 guard stop 시 원래대로 복원합니다.
--protect는 현재 데모 중인 프로그램을 보호합니다(제목 기준으로 일치시킴, 반드시 전달).- 기본적으로 스킬 자신의 프로세스 트리에 있는 제어판 창만 숨기고, GUI는 숨기지 않습니다. 사용자의 세션 인터페이스는 계속 볼 수 있습니다.
- GUI도 함께 숨겨야 하는 경우
--hide-own-gui를 추가하세요. - 가드의 판단 기준은 '실제 중첩'입니다: 수집 영역에 몇 픽셀만 걸쳐 있는 창(다른 화면에 있는 경우)은 잘못 숨기지 않습니다.
3.3 사용자에게 녹화 시작 알림
사용자에게 명확히 알립니다: 녹화를 시작해 주세요. 완료되면 '녹화 완료'라고 답해 주세요. 사용자가 확인하기 전에는 조작을 시작하지 마세요. 그렇지 않으면 이 준비 동작이 녹화됩니다.
3.4 실제 조작 실행
챕터 순서대로 조작하며, 각 단계에서:
- 브라우저: CDP 요소 클릭 사용, 실제 마우스 움직이지 않음.
클릭 전에 좌표를 기록해 두었다가, 이후 주석에 사용:
python scripts/studio.py aim <프로젝트> <x> <y> --note "내보내기 형식". - 데스크탑 소프트웨어: 창 활성화 + 키보드 우선; 실제 클릭이 필요한 경우 실제 마우스를 사용하지만, 녹화 중에는 사용자가 마우스를 움직이지 않도록 주의시킵니다.
- 상태 확인이 필요한 경우, 사용자를 방해하지 않고 직접 한 프레임을 캡처하여 확인합니다:
python scripts/studio.py shot --out <프로젝트>/build/check.png
- 로그인, 권한 부여, 인증 코드: 녹화를 유지하며 사용자가 직접 수행하고, 스킬은 성공 여부만 확인합니다. 자격 증명, 인증 코드, 키는 편집 시 잘라냅니다. 로그인 전과 후에 분할 녹화한 다음, 의존 순서에 따라 이어붙일 수 있습니다.
- 스킬의 모든 명령은 창 없이 실행되어야 합니다:
scripts/h.ps1은CreateNoWindow로 자식 프로세스를 시작하고, 스킬 내부 자식 프로세스는 모두CREATE_NO_WINDOW를 사용합니다.
3.5 사용자에게 녹화 중지 알림
조작을 모두 완료한 후 즉시 사용자에게 알립니다: 조작이 끝났습니다. 녹화를 중지하고 비디오 파일 경로를 알려주세요. 사용자가 경로를 반환할 때까지 기다립니다. 녹화 파일을 직접 찾거나 삭제하지 마세요.
3.6 마무리
python scripts/studio.py guard stop --project <프로젝트> # 가드 중지 및 창 복원
python scripts/studio.py guard status --project <프로젝트> # 수집 화면에 제어판이 남아 있는지 확인
guard status는 수집 영역에 여전히 보이는 제어판 클래스 창을 나열합니다. 비어 있어야 깨끗한 것입니다.
잔여 창이 있다면, 어떤 프로그램이 반복적으로 창을 띄우는 것이므로, 사용자에게 해당 구간을 다시 녹화하도록 요청하세요.
단계 4 · 자료 가져오기 및 인덱스 구축
python scripts/studio.py import --project <프로젝트> --file "D:\video\rec.mp4"
python scripts/studio.py index --project <프로젝트> --clip rec.mp4 --step 2
index는 고정 스텝으로 전체 녹화 영상을 스캔하고, 프레임 단위 OCR을 수행하여 다음을 기록합니다:
- 각 시점에 화면에 어떤 텍스트가 있는지 (특정 초에 무엇을 하고 있는지 조회)
- 시각적 변화 지점 (자연스러운 컷 포인트)
- 오염 구간 (제어판 / 알림 버블 / 시작 페이지, 피해야 할 부분)
build/index_<이름>.txt(직접 검색 가능)와 .json(구조화됨)을 생성합니다.
샷을 배치하기 전에 먼저 인덱스를 읽으세요. 시간 코드를 추측하지 마세요.
단계 5 · 샷 배치
build/plan.json:
{
"display": {"region": [0, 0, 1920, 1080]},
"voice": {"voice": "zh-CN-XiaoxiaoNeural", "rate": "+8%"},
"chapters": [
{
"id": "ch02", "num": "02", "title": "텍스트-이미지 생성", "sub": "세 부분으로 구성된 프롬프트, 재현도 결정",
"beats": [
{"seg": 0, "src": "rec.mp4", "in": 120, "out": 134},
{"seg": 1, "src": "rec.mp4", "in": 136, "out": 152, "zoom": 1.0}
],
"callouts": [
{"seg": 1, "offset": 1.0, "text": "프롬프트 세 부분\n캐릭터 → 소재 → 구도",
"x": 120, "y": 680, "pointer": "up"}
]
}
]
}
src는raw/디렉토리의 파일 이름입니다(import로 가져온 사용자 녹화본).in/out은 초 단위입니다.seg는 이 샷이 챕터 내에서 몇 번째 음성 대사를 위한 것인지 나타내며, 0부터 시작합니다.zoom> 1은 확대(정적 크롭 확대)를 의미합니다.callouts는seg+offset을 사용하여 주석이 나타나는 시점을 지정하며, 음성 대사와 함께 움직입니다.x/y는 주석 위치입니다(aim이 기록한 조작 좌표 사용 가능).- 챕터
id는script.md의 챕터 ID와 같아야 하며,audio_map.json의 세그먼트 접두사와도 같아야 합니다. - 전체 예시는
assets/plan.example.json을 참조하세요.
샷 배치 규칙:
- 한 샷은 하나의 조작 포인트를 다루며, 샷 길이는 해당 음성 대사의 길이에 의해 결정됩니다.
- 이름이 언급되기 전 또는 동시에 해당 컨트롤에 도달해야 합니다. 주요 피드백이 나타날 때는 읽을 시간을 남겨 둡니다.
- 인접한 컨트롤은 가능한 한 하나의 프레임에 함께 포함시키고, 자주 전환하지 마세요.
- 실제 대기 시간은 합리적으로 압축하되, '트리거 동작 → 처리 피드백'이 식별 가능한 시간은 유지하세요.
- 화면이 부족한 단락은 화면으로 증명할 수 있는 문장으로 다시 작성하거나, 추가 녹화하세요.
- 인덱스가 표시한 오염 구간을 피하세요.
단계 6 · 편집, 검증, 전달
python scripts/studio.py build --project <프로젝트>
python scripts/studio.py verify --video <프로젝트>/final.mp4 --expect-duration <음성 대사 총 길이>
build가 자동으로 수행: 문장별로 시간 맞춰 컷 전환 → 챕터 제목 카드 → 주석 오버레이 → 교차 디졸브 전환 트리 → BGM 사이드체인 음량 낮추기 → 음량 정규화.
BGM: 음악 파일을 build/bgm.wav(또는 build/bgm_final.wav)에 넣으면, 빌더가 음성 파형을 기반으로 음량 낮추기 곡선을 계산하여 믹싱합니다.
이 파일이 없어도 비디오는 생성되지만, 배경 음악은 없습니다.
감사 통과 실패 시: build/audit.txt의 시간 코드에 따라 창을 교체하거나 추가로 녹화하고, plan.json을 수정한 후 다시 실행하세요.
일반적인 방법은 오염된 in/out을 깨끗한 구간으로 전체 이동하거나, 사용자에게 해당 부분을 다시 녹화하도록 요청하는 것입니다.
전달 전 자체 점검:
- 파일이 완전히 재생되고, 영상과 음성 트랙이 완전하며, 길이가 음성 대사 총 길이에 근접합니다.
- 프레임 단위 OCR 감사 결과 문제가 없습니다.
- 정상 속도로 전체 영상을 보고 들으며, 다음을 중점적으로 다시 확인: 처음 3–10초, 각 기능 전환, 제출 및 결과, 숫자/고유명사, 대기 구간, 끝 부분.
- 각 설명 지점에 해당 커서 위치가 있습니다. 긴 정적 이미지 교체, 내용 없는 일시 중지, BGM이 음성을 덮는 경우가 없어야 합니다.
명령어 빠른 참조
studio init <프로젝트> # 프로젝트 구조 생성
studio windows # 창 목록 표시, 조작 대상 찾기
studio prep --project <프로젝트> --maximize-title "Chrome"
studio guard start --project <프로젝트> --protect "Chrome" # ★ 녹화 중 수집 화면 깨끗하게 유지
studio shot --out check.png # 한 프레임 캡처하여 상태 확인
studio aim --project <프로젝트> 1001 720 --note "내보내기 형식"
studio guard stop --project <프로젝트> # 가드 중지 및 창 복원
studio guard status --project <프로젝트> # 제어판 잔여 여부 확인
studio import --project <프로젝트> --file rec.mp4
studio index --project <프로젝트> --clip rec.mp4
studio voice --project <프로젝트>
studio build --project <프로젝트>
studio audit --project <프로젝트>
studio verify --video final.mp4
studio status --project <프로젝트>
참고
references/production.md— 화면 녹화, 음성 녹음, 편집, 믹싱, 검수 세부 사항references/troubleshooting.md— 증상 → 원인 → 해결 방법assets/plan.example.json— 샷 계획 전체 예시