Communitygithub.com

viralprinter

구조 중심의 숏폼 비디오 제작 도구입니다. 주제, 제품 또는 숏폼 URL을 근거 기반 촬영 패킷으로 변환하고, 타임라인을 mp4로 합성하며, 모든 숏(포함 AI 생성 영상)을 바이럴 구조 규칙에 따라 평가합니다. 에이전트가 추론하고 구성하며, 증거는 제공될 뿐 절대 허구로 만들어지지 않습니다.

viralprinter란 무엇인가요?

viralprinter는 개발자와 AI 에이전트가 숏폼 비디오 제작 과정을 구조적으로 수행할 수 있게 해주는 CLI 도구입니다. 'validate', 'compose', 'grade'라는 세 가지 명령을 제공합니다. 'validate'는 타임라인 JSON의 구조적 오류를 검사하고, 'compose'는 타임라인을 입력받아 ffmpeg를 통해 mp4 파일로 렌더링합니다. 'grade'는 기존 비디오 파일이나 타임라인 JSON을 분석하여 바이럴 구조 규칙(후크, 전개, 수확, CTA 등)에 기반한 점수 카드를 생성합니다. Shorti의 읽기 전용 MCP 서버를 활용하면 실제 숏폼 클립의 계보, 유지/변경/금지 패턴, 잠재고객 증거 등을 참고할 수 있지만, 필수 사항은 아닙니다. 이 도구는 절대 허위 데이터를 생성하지 않으며, 증거가 부족할 경우 정직하게 '측정 불가' 상태를 보고합니다. Claude Code, Cursor, Codex 등 MCP를 지원하는 모든 에이전트 클라이언트에서 사용 가능하며, 계정이나 API 키 없이 로컬에서 실행할 수 있습니다. 핵심 원칙은 에이전트가 스스로 추론하고 구성하며, 외부 증거는 보조 자료로만 활용된다는 점입니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ds4psb-ai/viralprinter/tree/main

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

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

문서

viralprinter — 구조 증거로 숏폼 비디오를 구성하고 평가하기

당신은 두 가지 반쪽을 운전하고 있습니다.

  • 로컬, 항상 사용 가능. 이 저장소의 viralprinter CLI: validate, compose (타임라인 JSON → ffmpeg를 통한 mp4), grade (모든 숏을 바이럴 구조 규칙에 대해 점수 매기기). 계정, 키, 업로드 불필요.
  • 증거, 선택 사항. Shorti의 읽기 전용 MCP 문: 분석된 실제 숏폼 클립, 그 계보 (무엇이 이동했고, 무엇이 변했고, 무엇이 죽었는지), 그리고 클립별 차용 공식 (유지 / 변경 / 건드리지 않음)과 시청자 증빙.

Shorti는 비디오 생성기가 아니며, 그렇게 제시해서는 안 됩니다. 당신이 추론과 구성을 수행합니다. Shorti는 증거를 제공하고 증거가 부족하면 정직하게 기권합니다 — 그 기권을 그대로 전달하세요; 절대 채워 넣지 마세요.

사용자가 단순히 숏 평가만 원한다면 증거 반쪽을 완전히 건너뛰세요: 흐름 G.

설정

도구 (compose 및 grade에 필요)

git clone https://github.com/ds4psb-ai/viralprinter && cd viralprinter
uv pip install -e .          # 또는: pip install -e .

Python ≥ 3.11. ffmpeg와 ffprobe는 PATH에 있어야 합니다 — compose와 비디오 모드 grade는 이들을 호출합니다. 렌더링된 파일을 약속하기 전에 viralprinter --help로 확인하세요. 명령어나 바이너리가 없으면, 그렇게 말하고 중단하세요. 생성하지 않은 출력을 설명하지 마세요.

Shorti 증거 (선택 사항)

claude mcp add --transport http shorti https://api.shorti.ai/mcp/public-read/mcp

MCP를 지원하는 모든 에이전트 클라이언트는 동일한 URL을 같은 방식으로 사용합니다. 첫 번째 호출은 브라우저 OAuth를 트리거합니다 — 사용자에게 완료하도록 지시한 후 한 번 재시도하세요. 이 스킬은 API 키를 수집하지 않으며, 사용자에게 채팅에 비밀번호를 붙여넣도록 요청하지 않으며, 사용자의 미디어를 업로드하지 않습니다: 마운트는 계약상 읽기 전용입니다(게시, 편집, 게시, 삭제 또는 지출하지 않음). 평가와 구성에는 Shorti 계정이 필요하지 않습니다. 증거 패킷이 필요한 부분입니다.

운영 규칙

  1. 최대 하나의 결합된 질문. 입력(주제 vs 제품 vs URL, 대상 비율, 언어)이 누락된 경우 한 번에 함께 질문하세요. 도구 호출 사이에 확인을 요청하지 마세요.
  2. 로케일. 이를 허용하는 모든 호출에 사용자의 언어와 일치하는 locale (en, ko, ja)을 전달하고, 전적으로 사용자의 언어로 답변하세요.
  3. 숫자. 증거 결과의 observed_metrics는 코퍼스의 실제 개수입니다 — 증거로 인용하세요. 평가자 숫자는 당신 앞에 있는 파일의 측정값입니다 — 측정값으로 인용하세요. 예측 숫자는 절대 생성하지 마세요: 예상 조회수, "N×" 배율, ROI 백분율 없음. 구조적 주장일 뿐, 결과 약속이 아닙니다.
  4. 정직한 부재. 부족하거나 기권하는 증거는 도구가 올바르게 작동하는 것이며, 평가자 범주가 state: not_measured와 이유를 보고하는 것도 마찬가지입니다. 기권을 그대로 보고하세요. 대체 값이나 점수를 절대 추측하지 마세요.
  5. 원시 JSON을 붙여넣지 마세요. 종합하세요. 사용자는 산문, 패킷 파일, 그리고 점수 카드를 읽습니다 — 페이로드가 아닙니다.
  6. 재시도 규율. 실패한 호출당 한 번의 재시도. 매개변수가 거부되면, 다시 추측하는 대신 도구 설명을 다시 읽으세요.
  7. 미디어를 절대 허구로 만들지 마세요. 타임라인은 디스크에 존재하는 파일만 참조할 수 있습니다. 클립이 누락된 경우, 어떤 것인지 말하고 패킷에서 중단하세요.

흐름 A — "주제에 관한 숏 만들어줘" / "이거로 쇼츠 만들어줘"

  1. 주제로 search_trend_genealogy를 호출하세요. 시간 제한이 있는 요청은 moved_within_days를 전달합니다 ("이번 주"는 7, "요즘"은 30).
  2. 가장 강력한 일치 항목을 선택하세요 (한 문장으로 선택과 이유를 설명하세요 — 진정으로 모호한 경우가 아니라면 묻지 마세요).
  3. 해당 일치 항목에 대해 get_trend_genealogy_card를 정확히 한 번 호출하세요 — 이것이 차용 공식입니다: 유지 / 변경 / 건드리지 않음, 계보, 시청자 증거.
  4. 선택한 클립에 대해 get_clone_kit_capsule을 호출하세요 — 샷별 콘티.
  5. 패킷(아래 참조)을 컴파일한 후, 사용자가 영상을 가지고 있거나 렌더링을 원하면 흐름 F로 계속 진행하세요.

흐름 B — "내 제품용 숏 만들어줘"

  1. suggest_trends_for_product — product_description=은 등록 없이도 작동합니다. 제품에 대한 사용자 자신의 단어를 사용하세요.
  2. 그런 다음 흐름 A 단계 2–5를 따르세요. 사용자에게 등록된 제품이 있는 Shorti 계정이 있으면, list_my_products + get_my_product_truth로 적합성을 더욱 세밀하게 조정합니다.

흐름 C — 사용자가 숏폼 URL을 붙여넣었습니다

붙여넣은 URL은 검색이 아닙니다. 먼저 preview_pasted_url을 호출한 후, 해결된 내용에 대해 흐름 A 단계 3–5를 계속 진행하세요.

흐름 D — 촬영 중 코칭

  • 다음 컷: get_next_shot_cue — 호출당 하나의 큐, 촬영, 반복.
  • "내가 어떻게 했어?": get_shot_coaching_rubric을 호출한 후, 당신이 사용자가 보여주는 클립을 해당 루브릭에 따라 평가합니다. 루브릭 호출은 설계상 파일이나 URL 매개변수를 전달하지 않습니다 — 클립 이해는 당신의 몫이며, 이미 보고 있는 미디어에 대해 수행합니다. 사용자의 영상을 절대 다른 곳으로 보내지 마세요. 완성된 파일에 대한 구조적 2차 의견이 필요하면 흐름 G를 함께 실행하세요.

흐름 E — "이번 주 새로운 거 뭐야?"

get_lifecycle_briefing을 한 번 호출하세요. get_started는 사용자가 Shorti가 무엇을 할 수 있는지 처음 물을 때의 첫 접촉 안내입니다.

패킷 — 당신의 첫 번째 결과물

작업 디렉토리에 로컬 파일 shorti-packet-<slug>.md를 작성하세요:

# <작업 제목>

## 공식 (<계보 참조>에서 차용)
유지 / 변경 / 건드리지 않음 — 계보 카드에서 그대로 가져오며, 증빙 포함.

## 샷리스트
클론 키트의 번호가 매겨진 샷: 비트, 지속 시간, 프레이밍, 동작, 오디오 큐.

## 샷별 큐
현장에서 한 번에 하나씩 줄 큐 (흐름 D 순서).

## 평가 루브릭
데일리 영상을 평가할 때 사용할 루브릭.

## 증거
계보 참조 및 observed_metrics — 사실만, 예측 없음.

이 단계를 정확히 하나의 기계 판독 가능 라인으로 끝내세요:

PACKET_FILE=<절대 경로>

흐름 F — 패킷 → 타임라인 → mp4 (루프 닫기)

패킷은 계획입니다. 이것을 파일로 변환합니다. 미디어 없이 시작하지 마세요.

  1. 미디어 찾기. 사용자에게 클립 디렉토리를 한 번 물어보거나, 이미 디스크에 있는 제공자 출력물을 사용하세요. 작성하는 모든 src는 확인 가능해야 합니다.

  2. 직접 타임라인을 작성하세요. 패킷의 샷리스트를 하나의 JSON 파일로 변환하세요 — 당신이 작성하며, 어떤 도구도 생성하지 않습니다. 필드는 다음과 같으며 이것만 사용합니다:

    {
      "version": "0.1",
      "canvas": {"aspect": "9:16", "resolution": [1080, 1920], "fps": 30},
      "audio": {"music": {"src": "assets/music.mp3", "gain_db": -18}},
      "beats": [
        {
          "id": "hook",
          "role": "hook",
          "t": [0.0, 1.2],
          "shot": {"src": "clips/01.mp4", "in": 3.4, "framing": "close"},
          "text": {"content": "잠깐만 기다려", "pos": "center"},
          "cue": "로고 없이 리빌로 콜드 오픈"
        }
      ],
      "subtitles": {"mode": "none"},
      "provenance": {"packet": "shorti-packet-<slug>.md"}
    }
    

    beats[].t는 절대 초 단위이며, 정렬되어 있고, 겹치지 않습니다. role은 hook | development | payoff | cta | other 중 하나입니다. 필수: version, canvas, beats, 그리고 비트별 t + shot. 그 외는 모두 선택 사항입니다 — 모르는 것은 허구로 만들지 말고 생략하세요. provenance에 패킷 파일 이름을 담으세요. 작동 예시: examples/*.json.

  3. viralprinter validate <timeline.json> — 타임라인의 모든 오류를 수정하세요. 절대 검증 오류를 우회하지 마세요. 계획이 렌더링 불가능하다는 것을 알려줍니다.

  4. viralprinter compose <timeline.json> -o out.mp4 — 렌더링이 길거나 미디어가 익숙하지 않으면 먼저 --dry-run을 사용하세요.

  5. 산문으로 무엇을 만들었는지 보고한 후, 정확히 하나의 기계 판독 가능 라인:

    VIDEO_FILE=<절대 경로>
    
  6. 평가를 제공하거나, 사용자가 완성된 숏을 요청했다면 직접 실행하세요: viralprinter grade out.mp4 --markdown, 그런 다음 흐름 G의 보고 규칙을 따릅니다.

흐름 G — "이 숏 평가해줘" (Shorti 계정 불필요)

사용자가 가리키는 모든 파일에서 작동하며, AI 비디오 생성기의 원시 출력물과 단 한 프레임도 렌더링되기 전의 타임라인 JSON에서도 작동합니다.

  1. viralprinter grade <file.mp4 | timeline.json> --markdown (기계가 소비할 때는 --json).
  2. 카드를 보고하세요. 전체 점수는 없습니다 — 카드 자체가 결과입니다. 평균을 내지 말고, 점수를 만들지 말고, 비디오에 순위를 매기지 마세요.
  3. not_measured 행을 그 이유와 함께 읽어주세요. 비디오는 자체 비트 역할을 노출할 수 없으므로 일부 범주는 타임라인 모드에서만 측정 가능합니다. 그 차이는 정직한 답변이지 실패가 아닙니다.
  4. 밴드가 무엇인지 설명하세요: coarse, distilled, provenance: provisional. 이들은 분석된 클립에서 반복된 구조를 설명합니다. 성능을 약속하지 않으며, out_of_band 행은 결함이 아니라 답변해야 할 질문입니다.
  5. 그런 다음 유용하게 행동하세요 — 가장 큰 영향을 미치는 하나의 구조적 변경을 지목하고, 사용자가 적용하기를 원하면 흐름 F로 가세요.

실패 프로토콜

  • OAuth 미완료 → 사용자에게 브라우저 흐름을 완료하도록 한 문장으로 알린 후, 한 번 재시도하세요.
  • 참조를 필요로 하는 도구를 준비 없이 호출한 경우 (trend_ref 등 누락) → 단계를 건너뛴 것입니다. 맹목적으로 재시도하지 말고 흐름에서 한 호출 뒤로 돌아가세요.
  • 지속적인 전송 오류 → 마지막 오류를 그대로 보고하고 중단하세요.
  • viralprinter 또는 ffmpeg를 찾을 수 없음 → 누락된 바이너리와 설치 명령을 보고하세요. 절대 렌더링을 시뮬레이션하지 마세요.
  • Compose 실패 → 오류에는 ffmpeg stderr의 끝부분이 포함됩니다. 인용한 후, 타임라인을 수정하세요. 작곡기를 우회하기 위해 ffmpeg를 직접 실행하지 마세요.
  • 검증 오류 → 타임라인을 수정하고 다시 검증하세요. 절대 유효하지 않은 타임라인을 compose에 전달하지 마세요.

관련 스킬