Renderizador de Vídeo com Um Clique
Descrição Funcional
Com uma única chamada, utiliza a API Chanjing para realizar TTS de narração, síntese de avatar digital, geração de vídeo a partir de texto e encapsulamento local. Integra ffmpeg / ffprobe para concatenação, transcodificação e alinhamento de faixas. Detalhes de orquestração e segurança estão nas §3–§8 e em templates/; o comando de saída final está na §5.
Dependências de Execução
Binários ou encapsulamentos equivalentes devem estar disponíveis (para detalhes de chamada, veja §5, run_render.py):
- ffmpeg: concatenação, transcodificação, encapsulamento
- ffprobe: metadados como duração, resolução, rotação (para alinhamento com a faixa do avatar digital)
- chan-skill (ou chamada direta
pythonpara scripts de sub-habilidades no mesmo repositório): para acionar CLIs comochanjing-tts,chanjing-video-compose,chanjing-ai-creation
Variáveis de Ambiente e Declarações Legíveis por Máquina
- Variáveis de ambiente opcionais para sobrescrita (todas com valores padrão ou inferência de caminho, não obrigatórias antes da execução): no topo de
scripts/run_render.pye no código-fonte das sub-habilidades; caminho de credenciais emmanifest.yamlcredentials. permissions,clientPermissions,agentPolicy, modelo de credenciais em conformidade:manifest.yaml
§3.2 alinhado com run_render.py; em caso de conflito com manifest.yaml, prevalece manifest.yaml.
Comandos de Uso
- ClawHub (slug conforme registro, geralmente igual ao nome do pacote da habilidade):
clawhub run chanjing-one-click-video-creation - Conexão direta com este repositório:
python scripts/run_render.py --input workflow.json --output-dir ./outputs/run1(usar no diretório da habilidade ou em conjunto comSKILLS_DIR/CHANJING_ONE_CLICK_VIDEO_SKILLS_ROOT/CHAN_SKILLS_DIR)
Consulta Rápida
| Conteúdo | Localização |
|---|---|
Fluxo de trabalho, duration_sec, null/mesclagem, validação de tópico | §4.1 |
Segmentação de texto, alternância par/ímpar, scenes[], scene_count/video_type; primeira cena voiceover ≤20 caracteres (rígido) | storyboard_prompt.md início "Segmentação de texto"; script_prompt.md narração da primeira cena; video_brief_plan.md |
Tecnologia de renderização, status, partial/success, restrições rígidas | render_rules.md §1–§4; §7, §8 |
ref_prompt / prompt de texto-para-vídeo | storyboard_prompt.md + history_storyboard_prompt.md; §4.2 ponteiros |
| Campos do corpo da requisição e valores padrão | §6 |
run_render.py, subprocessos CLI | §5 |
| Segurança, credenciais, perímetro de confiança, política | manifest.yaml + §3.1 (§3.1 não repete tabela do manifest) |
| Variáveis de ambiente, binários, efeitos colaterais, persistência em disco | §3.2 |
Conflitos: a implementação de renderização segue render_rules.md; as regras de ref_prompt seguem storyboard_prompt.md / history_storyboard_prompt.md (§4.2 são ponteiros de resumo). run_render.py implementa apenas §5 + render_rules.md, sem adicionar regras de negócio. Execução: orquestração manual de sub-habilidades, apenas run_render, ou uma combinação.
1. O que Faz
- Tópico ou texto completo →
video_plan, texto completo da narração, storyboard - TTS: segmento inteiro prioritário; se muito longo, mesclar em poucos lotes por cena (detalhes e contagem de caracteres em
render_rules.md§3·C.4) - Cortar áudio por cena
- Cenas com avatar digital:
chanjing-video-compose(áudio como driver) - Cenas de IA:
ref_prompt→chanjing-ai-creation→ sintetizar com áudio da cena - Encapsulamento: alinhar faixa pública do avatar digital → ffmpeg concat → mp4 local
2. Quando Usar / Quando Não Usar
| Adequado | Quando se deseja o vídeo finalizado; narração com edição de cenas; o usuário explicitamente pede a geração de um vídeo curto |
| Não adequado | Apenas texto/rascunho; sem pedido de vídeo; apenas edição de material existente |
3. Pré-requisitos
- Autenticação:
chanjing-credentials-guard; caminho e campos de credenciais emmanifest.yaml, §3.1; quando não houver credenciais, o subprocesso pode usaropen_login_page.py - Plano/Roteiro/Storyboard: lógica local do agente, sem necessidade de chave de API LLM externa (este caminho obrigatório da habilidade não depende de LLM externo)
- Binários locais e estrutura do repositório: §3.2 (
ffmpeg/ffprobe,SKILLS_DIRetc.) - Avatar digital e timbre de voz: Não usar variáveis de ambiente ou arquivos em cache no repositório para armazenar
audio_man/person_id/figure_type"padrão" entre tarefas. Em cada tarefa, preencher explicitamente na raiz doworkflow.json; o agente, com base novideo_plan(comovideo_type), persona da narração e semântica do tópico, deve usarlist_voices.pyelist_figures.py(com--sourceigual acommon/customisedetc., consistente com a tarefa atual) para selecionar e escrever os valores;audio_mandeve ser consistente com oaudio_man_idda figura selecionada. - Seleção de avatar digital público (proibido "apenas pegar os primeiros itens da lista"): usar
list_figures.py --source common --jsonpara obter candidatos (aumentar--page-sizeou paginar se necessário, para cobrir itens suficientes), comparar cada item dentro dos candidatos antes de finalizar:name,figures[].type(→figure_type),figures[].width/height(consistente com a proporção da tela em D.1c),audio_man_id,audio_name(se houver) e verificar a compatibilidade com ovideo_plan/persona da narração (gênero, estilo, setor, faixa etária). Preferência padrão por figuras jovens e animadas: priorizar nomes ouaudio_nameque contenham sinais positivos como jovem/menina/moço/aluno/energia/juventude/jovem; escolher a persona correspondente apenas quando o tópico ou o usuário solicitar explicitamente uma imagem madura, autoritária, de meia-idade ou idosa. A fonte personalizadacustomisedtambém deve ser comparada porname,width/height,audio_man_idetc., sem pegar o primeiro item da página sem comparação.
3.1 Segurança, Credenciais e Perímetro de Confiança
Variáveis de ambiente e binários seguem manifest.yaml e §3.2. Ao revisar, consultar description e manifest.yaml (incluindo agentPolicy).
- Capacidades e pipeline: descrição passo a passo na §1; responsabilidades de
run_rendere subprocessos na §5 (não repetir a cadeia aqui). - Credencial principal / caminho / primaryEnv: em
manifest.yaml; caminho e comportamento de gravação também na tabela de persistência §3.2 "Estado das credenciais" e emCHANJING_OPENAPI_CREDENTIALS_DIR(compatível comCHANJING_CONFIG_DIR). - Sensível e conformidade: não exibir chaves secretas completas, não submeter
credentials.jsonao controle de versão; permissões recomendadas0700/0600(os scripts de configuração devem tentar definir). - Confiança e comportamento de saída: HTTPS, baixar mídia das URLs retornadas, gravação em
--output-diretc., conforme tabela "Efeitos colaterais típicos" e tabela de persistência na §3.2; avaliar a confiabilidade do主机 Chanjing e dos links. - Navegador:
webbrowser.open/open_login_page.pyquando faltarem credenciais, na mesma tabela da §3.2. - Política do agente:
agentPolicyemmanifest.yaml(nãoalways, não modifica outras habilidades).
3.2 Contrato de Execução (Variáveis de Ambiente, Binários, Efeitos Colaterais e Gravação em Disco)
Alinhado com o comportamento de scripts/run_render.py e sub-habilidades no mesmo repositório; consistente com o YAML no início e com manifest.yaml. Se houver paralelismo com outra documentação de produto, a fonte do código deste repositório, manifest.yaml e este documento prevalecem.
Variáveis de Ambiente (sobrescrita opcional)
A nomeação segue a §3 de 合规规则.md na raiz do repositório. A lista não enumera novamente cada variável opcional: o sistema pode ser executado sem defini-las. Diretório de credenciais em manifest.yaml credentials (directoryEnv, defaultPath). openapi_base_url, one_click_skills_repository_root, one_click_ref_prompt_max_chars, one_click_ai_creation_model_code dentro de run_render.py e o ambiente dos subprocessos são a implementação desta habilidade para sobrescrita opcional e compatibilidade com nomes antigos.
Observação: variáveis como
FIRST_DIGITAL_HUMAN_MAX_CHARSem documentação externa, atualmente não são lidas porrun_render.py.
Binários Externos
| Binário | Obrigatoriedade | Uso |
|---|---|---|
ffmpeg | Obrigatório ao executar run_render.py para vídeo com um clique | Concatenação, transcodificação, encapsulamento de áudio/vídeo. Pode ser omitido se houver apenas orquestração pura de API sem executar este script de renderização. |
ffprobe | Mesmo que acima | Ler metadados de resolução, duração, rotação etc. para alinhamento com a faixa do avatar digital. |
Efeitos Colaterais Típicos ao Executar o Script (por Categoria)
| Tipo | Descrição |
|---|---|
| HTTPS de saída | Chamadas à API Chanjing Open (CHANJING_OPENAPI_BASE_URL / compatível com CHANJING_API_BASE), e download de materiais como video_url / URLs de áudio retornados pela interface/CDN. |
| Arquivos locais | Em run_render.py --output-dir são comuns: final_one_click.mp4, workflow_result.json, work/ (áudio intermediário, vídeos segmentados, lista concat etc.); detalhes conforme comando atual e templates/render_rules.md. |
| Subprocessos | ffmpeg / ffprobe; run_render chama via subprocess os CLIs Python em skills/chanjing-tts, chanjing-video-compose, chanjing-ai-creation no mesmo repositório. |
| Navegador | Quando faltam credenciais ou é necessário orientar o login, a cadeia de autenticação pode usar webbrowser.open ou executar open_login_page.py de chanjing-credentials-guard (consistente com o comportamento de _auth.py de cada habilidade). |
Escopo de Mudanças Persistentes e Controlabilidade pelo Usuário
Os itens abaixo são efeitos colaterais esperados para esta habilidade; a localização da gravação pode ser controlada por caminho e variáveis de ambiente, sem poluir implicitamente diretórios não relacionados.
| Categoria | O que é Gravado | Localização Típica | Como o Usuário Controla |
|---|---|---|---|
| Estado das credenciais | app_id / secret_key após configuração, access_token, expire_in após renovação etc. | CHANJING_OPENAPI_CREDENTIALS_DIR/credentials.json (padrão ~/.chanjing/credentials.json; compatível com CHANJING_CONFIG_DIR) | Definir o nome recomendado ou antigo; ou mover/remover o arquivo; não submeter chaves secretas ao controle de versão. |
| Artefatos do vídeo com um clique | final_one_click.mp4, workflow_result.json, work/ etc. | Especificado por run_render.py --output-dir (comum em outputs/<nome da tarefa>/ sob uma tarefa específica) | Usar --output-dir explícito; após a tarefa, manter ou remover o diretório conforme necessário. |
| Outros scripts de download (sub-habilidades) | Resultados da síntese etc. para o local | Scripts como download_result.py de cada habilidade: padrão em outputs/<linha de produto>/ no diretório de trabalho atual, ou caminho absoluto --output | Executar no cwd esperado, ou sempre passar --output; consultar o SKILL.md da habilidade correspondente. |
| Arquivos temporários/intermediários | Mesclagem TTS, segmentação, cache antes do upload etc. | Geralmente em work/ sob o output-dir acima ou subdiretórios definidos pelo script | Gerenciar junto com o diretório de saída. |
Arquivo de credenciais: caminho e semântica de leitura/escrita na linha Estado das credenciais da tabela acima; configuração inicial em skills/chanjing-credentials-guard/SKILL.md.
4. Compilação de Regras
4.1 Orquestração do Fluxo de Trabalho
Mesclagem: null = não sobrescrever. Ordem: valor padrão base → sobrescrita com não null → correção booleana/inteira. Valores padrão dos campos na §6; padrões não expandidos na tabela são lidos por run_render.py (e subprocessos) conforme implementação e variáveis de ambiente (exceto timbre/avatar: audio_man, person_id/avatar_id, figure_type vêm apenas do workflow.json, ver §3).
duration_sec: referência de planejamento, não limite para ffmpeg. Duração do vídeo final baseada em TTS + ffprobe. scene_count em video_brief_plan.md; segmentação e número de cenas de IA conforme medição real e eixo de legendas (render_rules.md §3·C.5). Proibido cortar narração já finalizada para atingir duração (a menos que o usuário solicite).
Tópico: remover espaços em branco <5 caracteres, strings placeholder (como "Olá", "teste") rejeitar; pode ser expandido; modo estrito: se vago, falhar.
Etapas: 1) Plan → video_brief_plan (falha geral se falhar; template em video_brief_plan.md) 2) Script (hook / primeira seção alinhada com primeira cena: ≤20 caracteres limite rígido, ver script_prompt.md) 3) Storyboard: segmentação semântica; storyboard_prompt.md (primeira cena voiceover com o mesmo limite rígido); não contemporâneo history_storyboard_prompt.md; DH chanjing-video-compose, IA chanjing-ai-creation; TTS/múltiplas cenas IA/mux render_rules.md §3, §5 4) Render: render_rules.md §3 (incluindo §3·C.6), §4 (Tabelas 4–6); controle de qualidade ref_prompt em storyboard_prompt.md / history_storyboard_prompt.md (§4.2); repetição/partial render_rules.md §1 5) Sucesso: render_rules.md §1
Apenas renderização: run_render.py + full_script + scenes[]. Ordem: Plan → Script → Storyboard → Render (qual template usar em cada fase, ver etapas acima).
4.2 Prompt de Texto-para-Vídeo (ref_prompt) — Ponteiros
Única fonte verdadeira das regras (revisões seguem os templates, este documento não repete o texto das tabelas D.1–D.4):
| Escopo | Template |
|---|---|
Orientação contemporânea, D.0 contexto padrão e inferência de círculo civilizacional, D.1 comprimento, D.1a, D.1b (propenso a alucinações, compartilhado por toda a habilidade), D.2 contemporâneo, visual_prompt manual, D.3, D.4 montagem contemporânea e 7 elementos / clusters de tema / montagem de cena única / auto-verificação | templates/storyboard_prompt.md → "Prompt de texto-para-vídeo (valor real orientação contemporânea)" |
| D.2 não contemporâneo encaminhamento, histórico nível de fluxo, consistência de círculo civilizacional e país, disciplina de placeholder, explicação de transição com D.3/D.4 | templates/history_storyboard_prompt.md |
| Etnia, figuras históricas/não contemporâneas de estilo chinês e frases curtas em inglês ao aparecer figuras | templates/visual_prompt_people_constraint.md (âncora explícita de etnia, seção histórico / não contemporâneo; também render_rules.md §4 Tabelas 4–6) |
Ainda apenas indexado aqui: múltiplas seções de áudio longo render_rules.md §3·C.6; limite de caracteres CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS (compatível com AI_VIDEO_PROMPT_MAX_CHARS). Em caso de conflito entre template e implementação em render_rules.md, prevalece render_rules.md.
5. Orquestração Automatizada (run_render.py)
Dependências: autenticação; SKILLS_DIR / CHANJING_ONE_CLICK_VIDEO_SKILLS_ROOT / CHAN_SKILLS_DIR (§3); chanjing-tts / chanjing-video-compose / chanjing-ai-creation
Responsabilidades: ① TTS + audio_task_state; mesclagem em lote e limite de caracteres por lote em render_rules.md §3·C.4 (TTS_BATCH_MAX) ② Segmentação (render_rules.md §3·C.5) ③ Quando houver cena de IA, primeiro completar a primeira cena de avatar digital e usar ffprobe (incluindo rotate) → depois enviar as cenas de texto-para-vídeo com aspect_ratio/clarity mapeados (ver render_rules.md §3·C.6, debug.ai_video_submit_params) ④ Polling paralelo com as outras DH/AI ⑤ Alinhar a faixa de IA com a referência do ffprobe ⑥ ffmpeg concat ⑦ Para múltiplas cenas de texto-para-vídeo, anexar segmentação em inglês após ref_prompt; comprimento total limitado por CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS (compatível com AI_VIDEO_PROMPT_MAX_CHARS)
Não faz: não gera plan/script/storyboard; não alterna automaticamente entre não contemporâneo/contemporâneo; não usa list_tasks.py para contemporâneo secundário (render_rules.md §4 item 8)
Orquestração manual: ainda deve satisfazer render_rules.md §3, §4 e §5; os detalhes da §3 (como silencedetect, minterpolate, bitrate da faixa de referência, troca de figura com o mesmo áudio segmentado, silêncio entre lotes TTS etc.) são todos preservados.
Input MVP
| Campo | Obrigatório | Descrição |
|---|---|---|
full_script | Sim | Combinado com voiceover de cada cena por scene_id, norm consistente |
scenes | Sim | scene_id, voiceover, use_avatar; cena de IA ref_prompt (storyboard_prompt.md / history_storyboard_prompt.md; §4.2); opcional subtitle |
audio_man | Sim | Deve ser consistente com o audio_man_id da figura de avatar digital selecionada |
person_id/avatar_id | Condicional | Obrigatório se houver cena de avatar digital |
figure_type | Não | Deve ser consistente com o figure_type da linha da figura selecionada em list_figures.py (obrigatório para figuras públicas com múltiplas formas) |
subtitle_required | Não | Padrão false; quando true, queima legendas na cena de avatar digital (--subtitle show) |
speed/pitch | Não | Padrão 1/1 |
ai_video_duration_sec | Não | 5 ou 10, padrão 10 |
model_code | Não | Padrão CHANJING_ONE_CLICK_VIDEO_CREATION_MODEL_CODE (compatível com AI_VIDEO_MODEL) ou Doubao-Seedance-1.0-pro; creation_type=4; não enviar ref_img_url |
max_retry_per_step | Não | Padrão 1 (§6) |
python scripts/run_render.py --input workflow.json --output-dir ./outputs/run1
Saída: final_one_click.mp4; workflow_result.json; work/
6. Entrada (Corpo da Requisição)
norm: remover \r, espaços em branco no início/fim; vazio → string vazia; consistente com run_render.py. Narração: primeiro full_script, depois script → copy_text → input_script → content primeiro não vazio. Sem topic: primeira frase substitui o tópico (se encontrar pontuação final dentro de 40 caracteres, cortar; senão, 24 caracteres). null/mesclagem §4.1.
| Campo | Obrigatório | Descrição |
|---|---|---|
topic | Condicional | Se não houver, usar regra da primeira frase; recomenda-se ≥5 caracteres |
industry/platform/style | Não | industry vazio; platform/style: DEFAULT_* ou douyin/观点型口播 (narração opinativa) |
duration_sec | Não | DEFAULT_DURATION ou 60; referência de planejamento |
use_avatar | Não | Padrão true |
avatar_id/voice_id | Não | Vazio; não usar variável de ambiente para timbre ou avatar como fallback; deve especificar audio_man/person_id (e figure_type se houver cena DH) no workflow.json, selecionados pelo agente usando list_voices.py e list_figures.py (fonte consistente com video_plan / especificação do usuário) após comparar name, forma, proporção de tela, audio_name etc.; proibido pegar os primeiros itens da lista sem comparação; preferência padrão por avatar digital jovem (ver §3) |
subtitle_required | Não | Padrão false (vídeo final de avatar digital não queima legendas; run_render envia hide) |
cover_required | Não | Padrão true |
strict_validation/allow_auto_expand_topic/max_retry_per_step | Não | true/false/1 |
full_script | Não | Padrão vazio |
script_title/script_hook/script_cta | Não | Padrão vazio |
script/… | Não | Ver ordem da narração acima |
7. Saída JSON
| Chave | Significado |
|---|---|
status | success / partial / failed |
video_plan | Plan |
script_result | title, hook, full_script, cta |
storyboard_result.scenes[] | scene_id, duration_sec, voiceover, subtitle, visual_prompt, use_avatar |
render_result | video_file, scene_video_urls, render_path, degrade_log |
| Outros | error, debug… |
Renderização sem degradação: se qualquer etapa falhar, interrompe imediatamente, sem alterar automaticamente para apenas DH ou apenas IA. partial: não atingiu success (por exemplo, exceção em run_render ainda grava workflow_result.json); não indica a degradação acima permitida, não isenta da verificação de qualidade do tipo storyboard_prompt.md·D.1b. Sucesso degrade_log=[]; falha tenta preservar o texto e storyboard já gerados.
8. Restrições Rígidas
Tabelas em templates/render_rules.md §4; interseção com ref_prompt em storyboard_prompt.md / history_storyboard_prompt.md (§4.2 são ponteiros). Esta seção é o ponto de ancoragem.
9. Limitações
- Saída local em mp4; não faz upload
- Cena única de IA geralmente 5–10s; narração longa resulta em múltiplas cenas
- Duração do vídeo final = faixa total do TTS; pode não corresponder a
duration_sec - TTS: faixa inteira prioritário, se muito longo, mesclar em poucos lotes; limite por lote e estratégia de mesclagem (incluindo
TTS_BATCH_MAX) conformerender_rules.md§3·C.4 - Falha de texto-para-vídeo pode ser devido à plataforma/modelo; tentar aumentar
max_retry_per_step, encurtarref_prompt, dividir cenas; consultarworkflow_result.json