Communitygithub.com

playthegameoflife/tiktok-screen-recorder

TikTok 동영상의 실제 화면 녹화를 생성하고 프레임 단위로 검증합니다. URL 캡처, 녹화, 화면 녹화 요청 또는 큐 파일에서 일괄 처리할 때 사용하세요. 헤드리스 Linux 환경에서 다운로드부터 검증된 출력까지 전체 파이프라인을 처리합니다.

tiktok-screen-recorder란 무엇인가요?

이 스킬은 TikTok 동영상의 정확한 화면 녹화를 생성하고 검증하는 자동화된 파이프라인을 제공합니다. 단순한 파일 크기나 재생 시간 확인으로는 감지할 수 없는 미묘한 녹화 오류(예: 마지막 1초 손실)를 `pipeline.sh`의 종료 코드와 `verify.py`의 프레임 비교를 통해 확실하게 검출합니다. 헤드리스 Linux 시스템에서 Xvfb, PulseAudio, ffmpeg, mpv를 함께 사용하여 실제 사람이 보는 것과 같은 화면 녹화를 구현하며, 세션 쿠키를 지원합니다. 큐 파일을 통한 일괄 처리도 가능하지만, 각 작업이 약 2 vCPU를 필요로 하므로 리소스 예산을 확인한 후 동시 실행해야 합니다. 종료 코드 10은 데이터센터 IP에서 흔히 발생하는 예상된 오류(차단됨, 비공개, 삭제됨)이며, 반복해서 재시도하지 않고 단순히 집계하여 보고해야 합니다. 종료 코드 14나 15가 반복되면 파이프라인 자체에 문제가 있는 것이므로 `manifest.json`의 `first_frame_mae`와 `last_frame_mae` 값을 참조하여 보고하고, 임계값을 조정하여 강제로 통과시키려 해서는 안 됩니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/playthegameoflife/tiktok-screen-recorder/tree/HEAD/hermes/skills/tiktok-capture

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

TikTok 캡처 파이프라인

pipeline.sh를 실행하세요. ffmpeg, mpv 또는 Xvfb 명령을 직접 유도하거나, 눈으로 또는 재생 시간을 기준으로 녹화 성공 여부를 판단하려 하지 마세요.

하나의 규칙

캡처가 성공했다고 절대 보고하지 마세요. 오직 pipeline.sh가 종료 코드를 통해 결정합니다.

이것이 중요한 이유는 마지막 1초를 조용히 잃어버린 녹화도 정확한 재생 시간과 정확한 프레임 수를 가지기 때문입니다. verify.py의 첫 프레임/마지막 프레임 비교만이 이를 잡아냅니다. 재생 시간이나 파일 크기를 확인하고 괜찮다고 넘어가고 싶다면, 바로 이 파이프라인이 존재하는 이유를 무시하는 것입니다.

단일 작업 실행

OUT_DIR=/data/out ./pipeline.sh "https://www.tiktok.com/@user/video/123"

소스에 세션이 필요한 경우 쿠키 사용:

OUT_DIR=/data/out COOKIES=/data/cookies.txt ./pipeline.sh "$URL"

일괄 실행

큐 파일에서 한 줄에 하나의 URL을 읽어 반복합니다. CPU 예산을 먼저 확인하지 않았다면 직렬로 실행하세요. 각 작업은 프레임 드롭 없이 30fps를 유지하기 위해 약 2 vCPU가 필요하며, 각 작업은 자체 PID에서 파생된 디스플레이 번호와 PulseAudio 인스턴스를 사용하므로 동시 실행이 충돌하지 않습니다.

while read -r url; do
    [ -z "$url" ] && continue
    OUT_DIR=/data/out ./pipeline.sh "$url" || echo "FAILED: $url"
done < queue.txt

종료 코드

코드의미수행할 작업
0검증됨출력 경로를 기록합니다. 다른 작업은 없습니다.
3종속성 누락중지하고 보고합니다. 재시도 불가능합니다.
10다운로드 실패예상된 오류입니다. 차단됨, 비공개 또는 삭제됨. 기록하고 넘어갑니다.
11소스에 오디오 없음기록하고 넘어갑니다.
12트랜스코딩 실패기록합니다. 한 번 재시도한 후 보고합니다.
13캡처 실패Xvfb/pulseaudio가 설치되어 있고 디스플레이 범위가 사용 가능한지 확인합니다.
14트리밍 실패리드인이 측정되거나 검증될 수 없습니다. 보고합니다. 맹목적으로 재시도하지 마십시오.
15검증 실패출력은 <output>.rejected에 있습니다. 파이프라인 결함으로 보고합니다.

종료 코드 10은 일상적인 오류입니다. 데이터센터 IP에서는 상당한 비율의 URL에 대해 예상된 결과입니다. 횟수로 보고하고, 반복 루프에서 재시도하지 마십시오.

반복적인 실패 시

종료 코드 14 또는 15는 비디오 자체가 아니라 파이프라인 자체에 문제가 있음을 의미합니다. 실행된 manifest.json 측정값(first_frame_mae 및 last_frame_mae)을 읽어 두 경우를 구분하십시오:

  • last frame MAE 높음, first frame MAE 낮음 → 리드인이 짧게 측정되어 종료 부분이 잘렸습니다.
  • 둘 다 높음 → 캡처가 정렬되지 않았거나 디스플레이가 업데이트되지 않았습니다.

강제로 통과시키기 위해 허용 오차를 조정하지 말고 숫자를 보고하십시오. --match-threshold를 높여 녹색 결과를 얻는 것은 해결책이 아닙니다.

관련 스킬