makunrui80-oss/freedom-video-skill

자유 비디오 생성 스튜디오

주제, 스크립트, 프롬프트 또는 Python 예제로부터 재현 가능한 비디오를 제작합니다. 결정적 장면과 코드 또는 다이어그램 애니메이션에는 Manim 렌더링이 필수입니다. 구성된 클라우드 비디오 모델을 통해 추가 푸티지를 추가하거나 생성할 수 있습니다. 워크플로우를 Codex, Claude, Gemini, OpenClaw, Hermes, DeepSeek, Kimi, WorkBuddy 또는 일반 Python 스크립트에서 이식 가능하게 유지하세요.

두 제공자 계층 분리

• 에이전트 제공자는 수업 계획, 내레이션, 자막, 프롬프트 및 Manim/Python 소스를 작성하는 데만 사용하세요. OpenAI 호환 채팅 엔드포인트는 DeepSeek, Kimi 또는 Hermes와 같은 제공자에 사용할 수 있습니다.
• 비디오 제공자는 비디오 클립을 생성하거나 향상시키는 데만 사용하세요. 비디오 작업을 채팅 완료 엔드포인트로 보내지 마십시오.
• Agnes Video 2.5 Flash를 선택적 기본값으로 취급하고, 필수 종속성으로 간주하지 마십시오.
• 제공자를 구성하거나 호출하기 전에 references/provider-config.md를 읽으세요.

필수 워크플로우

1. 출력 프로젝트 디렉토리를 생성하세요. 소스, 오디오, 자막, 렌더링 및 로그를 이 디렉토리 안에 보관하세요.

2. 수업을 작성하거나 렌더링하기 전에 다음을 실행하세요.

   python3 scripts/ensure_manim.py --project-root <OUTPUT_PROJECT>
   

   이 단계는 필수입니다. <OUTPUT_PROJECT>/.venv-manim에서 Manim을 찾거나 설치하고, 버전을 확인한 후 실제 스모크 렌더링을 수행합니다. 실패하면 중지하세요. 이후 렌더링에는 스크립트가 출력하는 Manim 실행 파일 경로를 사용하세요.

3. 내레이션이 필요한 경우, 생성하기 전에 다음 필수 설정을 실행하세요.

   python3 scripts/ensure_kokoro.py --project-root <OUTPUT_PROJECT>
   

   이 스크립트는 고정된 Kokoro 중국어 스택을 <OUTPUT_PROJECT>/.venv-kokoro에 설치하고, 요청된 kokoro-tts-zh 소스 리비전을 .vendor 아래에 보존하며, 선택한 모델/음성을 첫 번째 사용 시 다운로드하고 실제 스모크 테스트 WAV를 합성합니다. 어떤 단계라도 실패하면 중지하세요. 음성 및 내레이션 명령어는 references/audio-config.md를 참조하세요.

4. 시간이 지정된 수업 계획을 작성하세요. 각 장면에 대해 내레이션, 화면상 코드, 애니메이션, 자막 텍스트 및 지속 시간을 지정하세요. 코드 실행 개념, 상태 변경, 포인터, 추적, 다이어그램 및 결정적 교육 시각 자료에는 Manim을 사용하세요.

5. 장면 시간을 고정하기 전에 완전한 내레이션을 생성하세요. scripts/kokoro_narrate.py를 사용하고, 기본값으로 따뜻한 교육용 음성 zf_032를 속도 0.96으로 사용하세요. 하나의 음성과 일정한 중간 속도를 유지하고, 측정된 WAV 및 해당 매니페스트에 맞춰 시각 자료와 자막을 시간 조정하세요.

6. Manim 초안을 렌더링하고 측정된 지속 시간, 프레임 크기, 텍스트 경계, 코드 하이라이팅 및 전환이 내레이션 계획과 일치하는지 확인하세요.

7. 수업을 실질적으로 개선하는 경우에만 클라우드 비디오 제공자를 호출하세요. 과금 작업 전에 아래 안전 점검을 실행하세요.

8. 최종 비디오를 조립한 후 오디오, 자막 타이밍, 코드 가독성, 지속 시간 및 재생 가능한 출력을 확인하세요.

내레이션 소스 정책

• 모든 내레이션 비디오에는 통합된 kokoro-tts-zh 모델 제품군에서 제공하는 중국어 음성을 사용하세요.
• macOS say, Windows SAPI, 브라우저 음성 합성 또는 기타 운영 체제 음성을 자동 대체 수단으로 절대 사용하지 마십시오.
• Kokoro 설치, 모델 다운로드, 음성 로딩 또는 합성에 실패하면 중지하고 실패를 보고하세요. 기계적인 음성으로 조용히 대체하지 마십시오.
• Kokoro는 사전 설정된 음성을 제공합니다. 업로드된 임의의 화자를 복제하지 않습니다. 연결된 저장소의 복제 경로는 별도의 StableTTS 서브모듈과 이 스킬에 의해 자체 포함되거나 검증되지 않은 모델 가중치에 의존합니다. 복제 요청이 있을 경우, 별도로 구성되고 검증된 복제 백엔드와 사용자가 음성 사용 권한을 가지고 있다는 확인을 요구하세요.

필수 과금 전 점검

모든 클라우드 비디오 요청 전에:

1. 제공자의 현재 가격 엔드포인트 또는 현재 공식 가격 출처를 조회하세요.
2. 구성된 할당량 엔드포인트를 통해 계정 할당량/크레딧을 조회하세요.
3. 요청된 지속 시간, 해상도, 모델 및 제공자 가격을 사용하여 최대 예상 비용을 계산하세요.
4. 이를 VIDEO_MAX_COST_PER_TASK 및 사용 가능한 크레딧과 비교하세요.
5. 점검 결과를 <OUTPUT_PROJECT>/usage/video-usage.jsonl에 기록하세요.

가격이나 할당량을 알 수 없거나, 엔드포인트를 확인할 수 없거나, 크레딧이 부족하거나, 최대 비용을 초과하는 경우 작업을 제출하지 마십시오. 제공자가 무료 티어를 광고한다고 해서 현재 요청이 무료임을 증명하지는 않습니다.

재시도 및 폴링 규칙

• 무기한 재시도하지 마십시오.
• 비동기 작업에는 VIDEO_MAX_POLLS 및 VIDEO_POLL_INTERVAL_SECONDS를 사용하세요.
• 일시적인 네트워크 오류 또는 HTTP 429/5xx 오류는 최대 VIDEO_MAX_RETRIES번까지 상한 지수 백오프로 재시도하세요.
• 큐 가득 참, 용량 가득 참, 크레딧 부족, 인증, 유효성 검사 또는 가격 정책 오류의 경우, 제공자가 명시적으로 짧은 Retry-After를 제공하고 구성된 재시도 예산이 한 번의 재시도를 허용하지 않는 한 즉시 중지하세요.
• 상태 폴링이 실패했다는 이유만으로 대체 작업을 생성하지 마십시오. 먼저 원래 작업을 ID로 검색하세요.

사용량 원장

사전 점검 및 제공자 호출마다 하나의 JSON 객체를 <OUTPUT_PROJECT>/usage/video-usage.jsonl에 추가하세요. API 키나 인증 헤더는 절대 저장하지 마십시오. 포함 내용:

{"timestamp":"ISO-8601","provider":"name","model":"id","job_id":"id-or-null","requested_seconds":10,"actual_seconds":10,"call_count":1,"status":"succeeded","price_source":"endpoint-or-url","estimated_cost":0,"actual_cost":0,"currency":"USD","cost_known":true,"error":null}

제공자가 실제 비용을 반환하지 않는 경우 actual_cost를 null로 설정하고 cost_known을 false로 설정하세요. 조용히 0으로 기록하지 마십시오. 마지막에 총 호출 수, 생성된 지속 시간, 알려진 비용 및 비용을 알 수 없는 호출을 요약하세요.

출력 계약

최종 비디오와 함께 편집 가능한 Manim 소스, Kokoro 내레이션 WAV 및 매니페스트, 자막 파일, 제공자 안전 구성 템플릿, 렌더링 명령어 및 사용량 원장을 제공하세요. 사용된 Kokoro 음성/모델/속도를 명시하고, 클라우드 비디오 API가 호출되지 않은 경우 또는 비용을 확인할 수 없는 경우를 명확히 기술하세요.

소스, 로그, 프롬프트, 셸 기록, 스크린샷 또는 커밋된 .env 파일에 비밀 정보를 노출하지 마십시오. 환경 변수를 사용하고 .env.example 템플릿만 제공하세요.