Renderizador de Video con un Solo Clic
Descripción Funcional
Con un solo clic, invoca la API de Chanjing para realizar TTS de locución, síntesis de avatares digitales, generación de video a partir de texto y empaquetado local; integra ffmpeg / ffprobe para unir, transcodificar y alinear pistas. Las reglas de orquestación y seguridad se detallan en §3–§8 y en templates/; el comando de renderizado final se encuentra en §5.
Dependencias de Ejecución
Se requieren binarios disponibles o encapsulaciones equivalentes (la forma específica de invocación se detalla en §5 y run_render.py):
- ffmpeg: para unir, transcodificar y empaquetar
- ffprobe: para obtener metadatos como duración, resolución, rotación, etc. (alineación con pistas de avatar digital)
- chan-skill (o invocación directa con
pythona scripts de habilidades secundarias en el mismo repositorio): para ejecutar CLI comochanjing-tts,chanjing-video-compose,chanjing-ai-creation
Variables de Entorno y Declaraciones Legibles por Máquina
- Variables de entorno opcionales (todas tienen valores predeterminados o inferencia de rutas, no son obligatorias antes de la ejecución): en la parte superior de
scripts/run_render.pyy en el código fuente de las sub-habilidades; la ruta de credenciales se encuentra enmanifest.yamlcredentials. permissions,clientPermissions,agentPolicy, modelo de credenciales conformes:manifest.yaml
Se alinea con §3.2 y run_render.py; en caso de conflicto con manifest.yaml, prevalece manifest.yaml.
Comandos de Uso
- ClawHub (el slug se basa en el registro, generalmente coincide con el nombre del paquete de la habilidad):
clawhub run chanjing-one-click-video-creation - Conexión directa a este repositorio:
python scripts/run_render.py --input workflow.json --output-dir ./outputs/run1(en el directorio de la habilidad o junto conSKILLS_DIR/CHANJING_ONE_CLICK_VIDEO_SKILLS_ROOT/CHAN_SKILLS_DIR)
Referencia Rápida
| Contenido | Ubicación |
|---|---|
Flujo de trabajo, duration_sec, null/fusión, validación de temas | §4.1 |
División en segmentos, espejos pares/impares, scenes[], scene_count/video_type; voiceover del primer plano ≤ 20 caracteres (estricto) | Al inicio de storyboard_prompt.md «División de texto»; locución del primer plano en script_prompt.md; en video_brief_plan.md |
Tecnología de renderizado, estados, partial/success, restricciones estrictas | render_rules.md §1–§4; §7, §8 |
ref_prompt / prompt de texto a video | storyboard_prompt.md + history_storyboard_prompt.md; puntero en §4.2 |
| Campos del cuerpo de la solicitud y valores predeterminados | §6 |
run_render.py, subprocesos CLI | §5 |
| Seguridad, credenciales, límites de confianza, políticas | manifest.yaml + §3.1 (§3.1 no repite la tabla de manifest) |
| Variables de entorno, binarios, efectos secundarios, escritura en disco | §3.2 |
Conflictos: la implementación del renderizado se rige por render_rules.md; las cláusulas de ref_prompt se rigen por storyboard_prompt.md / history_storyboard_prompt.md (puntero de resumen en §4.2). run_render.py solo implementa §5 + render_rules.md, sin agregar reglas de negocio. Ejecución: orquestación manual de sub-habilidades, solo run_render, o una combinación.
1. Qué Hace
- Tema o texto completo →
video_plan, texto completo de locución, storyboard - TTS: prioridad al segmento completo; si es demasiado largo, se fusiona en pocos lotes por storyboard (detalles y límite de caracteres en
render_rules.md§3·C.4) - Cortar audio por plano
- Plano de avatar digital:
chanjing-video-compose(impulsado por audio) - Plano de IA:
ref_prompt→chanjing-ai-creation→ síntesis con el audio del plano - Empaquetado: alinear pistas de avatar digital común → ffmpeg concat → mp4 local
2. Cuándo Usarlo / Cuándo No Usarlo
| Adecuado | Para obtener un video final; edición combinada de locución e imágenes; el usuario solicita explícitamente generar un video corto |
| No adecuado | Solo texto/título; no se solicitó video; solo editar material existente |
3. Requisitos Previos
- Autenticación:
chanjing-credentials-guard; ruta y campos de credenciales enmanifest.yaml, §3.1; sin credenciales, los subprocesos pueden usaropen_login_page.py - Plan/Guion/Storyboard: lógica del agente local, no requiere clave API de LLM externa (la ruta obligatoria de esta habilidad no depende de LLM externos)
- Binarios locales y estructura del repositorio: §3.2 (
ffmpeg/ffprobe,SKILLS_DIR, etc.) - Avatar digital y tono de voz: No utilice variables de entorno ni archivos en caché dentro del repositorio para almacenar valores
audio_man/person_id/figure_type«predeterminados» entre tareas. Escriba explícitamente estos valores en el nivel raíz deworkflow.jsonpara cada tarea. El agente, basándose envideo_plan(comovideo_type), la personalidad del locutor y la semántica del tema, debe llamar alist_voices.pyylist_figures.py(con--sourcetomandocommon/customised, etc., que sean consistentes con la tarea actual) para seleccionar el tipo y luego escribir los valores;audio_mandebe coincidir con elaudio_man_idde la figura seleccionada. - Selección de avatar digital público (prohibido «tomar solo los primeros elementos de la lista») : debe usar
list_figures.py --source common --jsonpara obtener los candidatos (si es necesario, aumente--page-sizeo pagine para cubrir suficientes entradas). Luego, dentro de los candidatos, compare elemento por elemento antes de finalizar:name,figures[].type(→figure_type),figures[].width/height(consistente con la relación de aspecto en D.1c),audio_man_id,audio_name(si existe) y si coincide convideo_plan/la personalidad del locutor (género, estilo, industria, sensación de edad). Preferencia predeterminada por figuras jóvenes y enérgicas: priorice cuando el nombre oaudio_namecontenga señales positivas como joven/chica/chico/estudiante/vitalidad/juventud; solo cuando el tema o el usuario solicite explícitamente un estilo maduro, autoritario, de mediana edad o mayor, seleccione la personalidad correspondiente. Para la fuente personalizadacustomised, también comparename,width/height,audio_man_id, etc., no tome directamente los primeros elementos de la lista sin comparar.
3.1 Seguridad, Credenciales y Límites de Confianza
Las variables de entorno y los binarios se basan en manifest.yaml y §3.2. Al revisar, se puede consultar description y manifest.yaml (incluyendo agentPolicy).
- Capacidades y conducto: la explicación a nivel de paso se encuentra en §1; las responsabilidades de
run_rendery los subprocesos se encuentran en §5 (no se repite la cadena aquí). - Credenciales principales / ruta / primaryEnv: consulte
manifest.yaml; la ruta y el comportamiento de escritura también se detallan en la tabla de persistencia de §3.2 «Estado de credenciales» y enCHANJING_OPENAPI_CREDENTIALS_DIR(compatible conCHANJING_CONFIG_DIR). - Sensibilidad y cumplimiento: no muestre las claves completas, no envíe
credentials.jsonal repositorio; se recomiendan permisos0700/0600(el script de configuración debe intentar establecerlo). - Confianza y comportamiento de salida: HTTPS, descarga de medios desde las URL devueltas, escritura en
--output-dir, etc. Los detalles se encuentran en la tabla de «Efectos secundarios típicos» y persistencia de §3.2; debe juzgar por sí mismo si confía en el host y los enlaces de Chanjing. - Navegador:
webbrowser.open/open_login_page.pycuando faltan credenciales, consulte la misma tabla en §3.2. - Política del agente:
agentPolicyenmanifest.yaml(no always, no modifica otras habilidades).
3.2 Contrato de Ejecución (Variables de Entorno, Binarios, Efectos Secundarios y Escritura en Disco)
Se alinea con el comportamiento de scripts/run_render.py y las sub-habilidades en el mismo repositorio; es consistente con el YAML inicial, manifest.yaml. Si se enumera junto con otra documentación del producto, prevalecen el código fuente de este repositorio, manifest.yaml y este documento.
Variables de Entorno (Anulación Opcional)
Los nombres siguen la §3 de 合规规则.md en la raíz del repositorio. La lista no enumera las variables opcionales una por una: se puede ejecutar sin configurarlas. El directorio de credenciales se encuentra en 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 y el entorno de los subprocesos son la ubicación de implementación para la anulación opcional y la compatibilidad con nombres antiguos de esta habilidad.
Nota: Variables como
FIRST_DIGITAL_HUMAN_MAX_CHARSen documentación externa, actualmenterun_render.pyno las lee.
Binarios Externos
| Binario | Obligatoriedad | Uso |
|---|---|---|
ffmpeg | Obligatorio al ejecutar run_render.py para la creación con un solo clic | Unir, transcodificar, empaquetar audio/video, etc. No es necesario si solo se orquestan API puras sin ejecutar este script de renderizado. |
ffprobe | Igual que arriba | Leer metadatos de resolución, duración, rotación, etc., para alineación con pistas de avatar digital. |
Efectos Secundarios Típicos al Ejecutar el Script (por Categoría)
| Tipo | Descripción |
|---|---|
| HTTPS saliente | API abierta de Chanjing (CHANJING_OPENAPI_BASE_URL / compatible CHANJING_API_BASE), y descarga de materiales como video_url / URL de audio devueltos por la interfaz/CDN. |
| Archivos locales | Comunes en run_render.py --output-dir: final_one_click.mp4, workflow_result.json, work/ (audios intermedios, videos segmentados, listas concat, etc.); los detalles dependen del comando actual y de templates/render_rules.md. |
| Subprocesos | ffmpeg / ffprobe; run_render llama a través de subprocess a los CLI de Python en los directorios skills/chanjing-tts, chanjing-video-compose, chanjing-ai-creation dentro del mismo repositorio. |
| Navegador | Cuando faltan credenciales o se guía al inicio de sesión, la cadena de autenticación puede ejecutar webbrowser.open o open_login_page.py de chanjing-credentials-guard (consistente con el comportamiento de _auth.py de cada habilidad). |
Alcance de los Cambios Persistentes y Control por Parte del Usuario
Los siguientes son efectos secundarios esperados para esta habilidad; la ubicación de escritura se puede controlar mediante rutas y variables de entorno, sin contaminar implícitamente directorios no relacionados.
| Categoría | Qué se escribe | Ubicación típica | Cómo lo controla el usuario |
|---|---|---|---|
| Estado de credenciales | app_id / secret_key configurados, access_token, expire_in actualizados, etc. | CHANJING_OPENAPI_CREDENTIALS_DIR/credentials.json (por defecto ~/.chanjing/credentials.json; compatible con CHANJING_CONFIG_DIR) | Establecer el nombre recomendado o el nombre antiguo; o migrar/eliminar el archivo; no envíe la clave secreta al repositorio. |
| Artefactos de creación con un solo clic | final_one_click.mp4, workflow_result.json, work/, etc. | Especificado por run_render.py --output-dir (comúnmente outputs/<nombre de tarea>/ dentro de una tarea) | Elija un --output-dir claro; conserve o elimine el directorio según sea necesario después de que finalice la tarea. |
| Otros scripts de descarga (sub-habilidades) | Resultados de síntesis en local, etc. | Los download_result.py de cada habilidad, etc.: por defecto, en su mayoría en outputs/<línea de producto>/ en el directorio de trabajo actual, o ruta absoluta --output | Ejecutar en el cwd esperado, o pasar siempre --output; consulte el SKILL.md de la habilidad correspondiente. |
| Archivos temporales/de proceso | Fusión de TTS, división en segmentos, caché previa a la carga, etc. | Principalmente en work/ bajo el output-dir mencionado o en subdirectorios acordados por el script | Gestionarlos junto con el directorio de salida. |
Archivo de credenciales: la ruta y la semántica de lectura/escritura se encuentran en la fila de Estado de credenciales de la tabla anterior; la configuración inicial se encuentra en skills/chanjing-credentials-guard/SKILL.md.
4. Recopilación de Reglas
4.1 Orquestación del Flujo de Trabajo
Fusión: null = no anular. Orden: valor base predeterminado → anulación por no null → corrección booleana/entera. Los valores predeterminados de los campos se encuentran en §6; los valores predeterminados no enumerados en la tabla son leídos por run_render.py (y subprocesos) según la implementación y las variables de entorno (sin incluir tono de voz/avatar digital: audio_man, person_id/avatar_id, figure_type solo provienen de workflow.json, consulte §3).
duration_sec: referencia de planificación, no un límite superior de ffmpeg. La duración del video final se basa en TTS+ffprobe. scene_count se encuentra en video_brief_plan.md; la división en segmentos y el número de segmentos de IA dependen de la medición real y el eje de subtítulos (render_rules.md §3·C.5). Prohibido recortar locuciones ya finalizadas para cumplir con la duración (a menos que el usuario lo solicite).
Tema: rechazar si tiene menos de 5 caracteres después de eliminar espacios en blanco, o si contiene cadenas de marcador de posición (como «hola», «test»); se puede expandir; en modo estricto, si es ambiguo, fallar.
Pasos: 1) Plan → video_brief_plan (si falla, todo falla; la plantilla está en video_brief_plan.md) 2) Script (hook / alineación del primer párrafo con el primer plano: límite superior estricto de ≤20 caracteres, consulte script_prompt.md) 3) Storyboard: división semántica; storyboard_prompt.md (voiceover del primer storyboard con el mismo límite superior estricto**); para temas no contemporáneos: history_storyboard_prompt.md; DH chanjing-video-compose, AI chanjing-ai-creation; TTS/múltiples segmentos de IA/mux render_rules.md §3, §5 4) Renderizado: render_rules.md §3 (incluyendo §3·C.6), §4 (Tablas 4–6); control de calidad de ref_prompt en storyboard_prompt.md / history_storyboard_prompt.md (§4.2); reintentos/partial render_rules.md §1 5) Éxito: render_rules.md §1
Solo renderizado: run_render.py + full_script + scenes[]. Orden: Plan → Script → Storyboard → Renderizado (qué plantilla usar en cada etapa se indica en los pasos anteriores).
4.2 Prompts de Texto a Video (ref_prompt) — Puntero
Único valor verdadero de las cláusulas (las revisiones se basan en las plantillas; este documento no repite el texto de las tablas D.1–D.4):
| Ámbito | Plantilla |
|---|---|
Contemporáneo, D.0 valores predeterminados del contexto e inferencia del círculo cultural, longitud D.1, D.1a, D.1b (propenso a alucinaciones, compartido por toda la habilidad), D.2 contemporáneo, visual_prompt manual, D.3, D.4 ensamblaje contemporáneo y 7 elementos / clústeres de temas / ensamblaje de un solo plano / autoverificación | templates/storyboard_prompt.md → «Prompt de texto a video (valor verdadero contemporáneo)» |
| Enrutamiento D.2 no contemporáneo, capa de proceso histórico, coherencia del círculo cultural y país, disciplina de marcadores de posición, explicación de la conexión con D.3/D.4 | templates/history_storyboard_prompt.md |
| Etnicidad, modelado histórico/no contemporáneo de estilo chino y frases en inglés cuando aparecen personas | templates/visual_prompt_people_constraint.md (anclaje étnico explícito, sección histórico / no contemporáneo; también render_rules.md §4 Tablas 4–6) |
Aún solo se indexa aquí: audio largo de múltiples segmentos render_rules.md §3·C.6; límite de caracteres CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS (compatible con AI_VIDEO_PROMPT_MAX_CHARS). Si hay conflicto entre la plantilla y render_rules.md, prevalece render_rules.md.
5. Orquestación Automatizada (run_render.py)
Dependencias: autenticación; 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; fusión por lotes y límite de caracteres por lote en render_rules.md §3·C.4 (TTS_BATCH_MAX) ② División en segmentos (render_rules.md §3·C.5) ③ Si hay planos de IA, completar primero el primer avatar digital y usar ffprobe (incluyendo rotate) → luego enviar aspect_ratio/clarity de texto a video según el mapeo (consulte render_rules.md §3·C.6, debug.ai_video_submit_params) ④ Sondeo paralelo con el resto de DH/AI ⑤ Alinear la pista de IA con esa referencia ffprobe ⑥ ffmpeg concat ⑦ Para múltiples segmentos de texto a video, agregar capas en inglés después de ref_prompt; la longitud total está limitada por CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS (compatible con AI_VIDEO_PROMPT_MAX_CHARS)
No hace: no genera plan/script/storyboard; no cambia automáticamente entre contemporáneo/no contemporáneo; no usa list_tasks.py para el recuento contemporáneo (render_rules.md §4 tabla ítem 8)
Orquestación manual: aún debe cumplir con render_rules.md §3, §4 y §5; los detalles de §3 (como silencedetect, minterpolate, tasa de bits de pista de referencia, cambio de figura con el mismo audio de segmento, silencio entre lotes de TTS, etc.) se conservan todos.
MVP de Entrada
| Campo | Obligatorio | Descripción |
|---|---|---|
full_script | Sí | Combinado con voiceover de cada plano por scene_id, norm consistente |
scenes | Sí | scene_id, voiceover, use_avatar; para planos de IA: ref_prompt (storyboard_prompt.md / history_storyboard_prompt.md; §4.2); opcional subtitle |
audio_man | Sí | Debe coincidir con audio_man_id de la figura de avatar digital seleccionada |
person_id/avatar_id | Condicional | Obligatorio si hay planos de DH |
figure_type | No | Debe coincidir con figure_type de la fila de figura seleccionada en list_figures.py (obligatorio si la figura pública tiene múltiples formas) |
subtitle_required | No | Por defecto false; si es true, graba subtítulos en los planos de avatar digital (--subtitle show) |
speed/pitch | No | Por defecto 1/1 |
ai_video_duration_sec | No | 5 o 10, por defecto 10 |
model_code | No | Por defecto CHANJING_ONE_CLICK_VIDEO_CREATION_MODEL_CODE (compatible AI_VIDEO_MODEL) o Doubao-Seedance-1.0-pro; creation_type=4; no pasar ref_img_url |
max_retry_per_step | No | Por defecto 1 (§6) |
python scripts/run_render.py --input workflow.json --output-dir ./outputs/run1
Salida: final_one_click.mp4; workflow_result.json; work/
6. Entrada (Cuerpo de la Solicitud)
norm: eliminar \r, espacios iniciales y finales; vacío → cadena vacía; consistente con run_render.py. Locución: primero full_script, luego script→copy_text→input_script→content, tomar el primero no vacío. Sin topic: usar la primera oración como tema (cortar en el primer signo de puntuación de fin de oración dentro de 40 caracteres; de lo contrario, 24 caracteres). null/fusión §4.1.
| Campo | Obligatorio | Descripción |
|---|---|---|
topic | Condicional | Si no está, usar la regla de la primera oración; se recomienda ≥5 caracteres |
industry/platform/style | No | industry vacío; platform/style: DEFAULT_* o douyin/locución de tipo opinión |
duration_sec | No | DEFAULT_DURATION o 60; referencia de planificación |
use_avatar | No | Por defecto true |
avatar_id/voice_id | No | Vacío; No use variables de entorno para proporcionar un tono de voz o avatar digital predeterminado; debe escribir audio_man/person_id (y figure_type si hay planos de DH) en workflow.json, seleccionados por el agente llamando a list_voices.py y list_figures.py (con fuente consistente con video_plan / especificación del usuario) después de comparar name, forma, relación de aspecto, audio_name, etc. ; prohibido tomar los primeros elementos de la lista sin comparación; preferencia predeterminada por avatares digitales jóvenes (consulte §3) |
subtitle_required | No | Por defecto false (el video final de avatar digital no graba subtítulos; run_render pasa hide) |
cover_required | No | Por defecto true |
strict_validation/allow_auto_expand_topic/max_retry_per_step | No | true/false/1 |
full_script | No | Por defecto vacío |
script_title/script_hook/script_cta | No | Por defecto vacío |
script/… | No | Consulte el orden de locución anterior |
7. Salida JSON
| Clave | 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 |
| Otros | error, debug… |
Renderizado sin degradación: si algún paso falla, se interrumpe, sin cambiar automáticamente a solo DH o solo IA. partial: no se ha convertido en success (por ejemplo, si run_render falla, aún escribe workflow_result.json); no indica que se permita la degradación anterior, no exime del control de calidad de tipo storyboard_prompt.md·D.1b. En caso de éxito, degrade_log=[]; en caso de fallo, intentar conservar el texto y el storyboard ya generados.
8. Restricciones Estrictas
La tabla se encuentra en templates/render_rules.md §4; la intersección con ref_prompt se encuentra en storyboard_prompt.md / history_storyboard_prompt.md (puntero en §4.2). Esta sección es un ancla.
9. Limitaciones
- mp4 local; no se sube
- Los segmentos de IA suelen durar 5–10s; locuciones largas requieren múltiples segmentos
- La duración del video final = pista total de TTS; puede no coincidir con
duration_sec - TTS: prioridad a la pista completa; si es demasiado larga, fusionar en pocos lotes; el límite por lote y la estrategia de fusión (incluyendo
TTS_BATCH_MAX) se rigen porrender_rules.md§3·C.4 - El fallo de texto a video puede deberse a la plataforma/modelo; intente aumentar
max_retry_per_step, acortarref_prompt, dividir el plano; verifiqueworkflow_result.json