wecut

¿Qué hace wecut?

wecut renderiza un proyecto JSON en un MP4 (o GIF) con el FFmpeg instalado en esta máquina. Tú describes la edición; WeCut hace el trabajo de vídeo. Nunca llama a un servicio de red.

Si wecut no está en PATH, usa npx -y wecut (Node 16+) en su lugar en todos los comandos siguientes. Si WeCut está conectado como servidor MCP, los mismos pasos son las herramientas wecut_doctor, wecut_probe, wecut_validate, wecut_preview (devuelve los fotogramas como imágenes), wecut_render, wecut_list, wecut_schema, wecut_example, wecut_analyze (devuelve la hoja de fotogramas como una imagen), wecut_recipe_list, wecut_recipe_show, wecut_recipe_apply y wecut_recipe_from_project; pasa un proyecto como project (objeto) o projectFile (ruta).

Flujo de trabajo

1. Comprueba la máquina una vez: wecut doctor. Si informa que FFmpeg falta, sigue su hint (por ejemplo sudo apt-get install -y ffmpeg).
2. Coloca los medios en el espacio de trabajo. Cada ruta en un proyecto es relativa a la carpeta desde la que ejecutas wecut (o --root DIR). Las URLs no son aceptadas: descarga los archivos primero.
3. Examina los medios: wecut probe media/talk.mp4 media/music.mp3 da la duración, el tamaño, los fps y si hay audio. Usa estos números para from/to.
4. Escribe project.json (formato más abajo). wecut example podcast-clip imprime un ejemplo completo; wecut schema imprime el JSON Schema; wecut list muestra todos los estilos, fuentes, transiciones y nombres de filtros.
5. Valida: wecut validate project.json. Los errores devuelven un puntero JSON (/clips/0/to) y un hint. Corrige y repite.
6. Mira antes de renderizar: wecut preview project.json --at 0.5,3,10 escribe pequeños fotogramas JPG en out/preview/. Ábrelos y comprueba el encuadre, el tamaño del texto y la posición de los subtítulos.
7. Renderiza: wecut render project.json. Usa --preset draft para una comprobación rápida a 540p, el valor por defecto final para entrega.

Cada comando imprime un objeto JSON. Códigos de salida: 0 correcto, 2 entrada no válida, 3 dependencia faltante, 4 error de renderizado, 5 sobre un límite. Puedes canalizar un proyecto con wecut render -.

Formato del proyecto

{
  "wecut": "1",
  "output": { "file": "out/clip-01.mp4", "ratio": "9:16", "res": 1080, "fps": 30 },
  "clips": [
    { "src": "media/talk.mp4", "from": 754.2, "to": 781.0, "focus": { "x": 0.42, "y": 0.5 } },
    { "src": "media/talk.mp4", "from": 795.5, "to": 812.0, "zoom": 1.15 }
  ],
  "texts": [
    { "text": "Cómo hice mis primeros $10k", "start": 0, "end": 3, "style": "hook", "y": 0.2, "in": { "type": "pop" } }
  ],
  "captions": { "words": "media/talk.words.json", "src": "media/talk.mp4", "style": "karaoke" },
  "audio": [ { "src": "media/music.mp3", "volume": 25, "loop": true, "duck": true, "fadeOut": 1.5 } ]
}

Reglas importantes:

• Dos relojes. from/to de un clip son segundos del archivo fuente. Todo lo demás (texts, overlays, audio.at, filters, effects) son segundos del vídeo terminado. wecut validate imprime la duration terminada.
• Las transiciones se superponen. Una transition en el clip N se funde con el clip N+1 y acorta el vídeo por su duration.
• Encuadre. El fit por defecto es cover (rellena y recorta). Dirige el recorte con focus (0..1; x 0.3 mantiene el lado izquierdo) y zoom. Usa "fit": "contain" con "background": "blur" para mostrar el fotograma completo.
• Las posiciones son fracciones del lienzo, 0.5 es el centro. El size de la fuente son píxeles a 1080p.
• Las imágenes usan duration (por defecto 3) y pueden tener motion: in, out, left, right, up, down.
• Los emojis no se dibujan en el texto. Ponlos en un PNG y usa overlays.

Subtítulos

Dale a WeCut una transcripción con tiempos de palabras y construye subtítulos:

• words: una ruta a .json, .srt o .vtt, o un array inline [{"word": "hola", "start": 0.1, "end": 0.4}]. Se aceptan verbose_json de OpenAI/Groq y el JSON de whisper.cpp tal cual.
• src: establece esto al vídeo al que pertenece la transcripción. Entonces la transcripción conserva los tiempos del archivo fuente, y WeCut mueve cada palabra a la línea de tiempo de salida a través de cada clip cortado de ese archivo (incluyendo la velocidad). Sin src, los tiempos ya deben ser tiempos de salida.
• style: classic, yellow, box-black, box-white, bold, comic, shadow (una frase a la vez), karaoke, karaoke-green (la palabra hablada se ilumina), pop (una palabra grande a la vez).

Si necesitas una transcripción: wecut doctor informa local_transcription: true cuando este FFmpeg tiene el filtro Whisper. De lo contrario, usa cualquier reconocimiento de voz que ya tengas y guarda sus tiempos de palabras como JSON.

Plantillas: copia lo que funciona

Una receta es la forma de una edición sin su contenido: secciones (por ejemplo, un gancho de 5 s con una tarjeta de titular, luego la charla), ranuras de texto, estilo de subtítulos y música, efectos. Aplicarla a nuevos clips, palabras y música da un proyecto.

1. Analiza un vídeo que funcionó: wecut analyze media/viral.mp4 devuelve tomas y ritmo, cortes en los primeros 3 s, destellos, tempo, pausas, un outro de plataforma silencioso (déjalo fuera) y sheet: un fotograma por toma en una sola imagen. Mira la hoja para la tarjeta de titular, estilo de texto, encuadre y estilo de subtítulos.
2. Elige o escribe una receta: wecut recipe list (incorporadas: news-headline, news-headline-blur, quote-hook, vlog-phrases, podcast-punch, photo-slideshow, más los recipes/*.json del espacio de trabajo). wecut recipe show <name> enumera sus roles y ranuras de texto. Para escribir una, sigue wecut recipe schema.
3. Aplícala:

{
  "recipe": "news-headline",
  "clips": [
    { "src": "media/broll.mp4", "role": "hook" },
    { "src": "media/talk.mp4", "from": 120, "to": 165 }
  ],
  "texts": { "label": { "text": "Nombre de la página" }, "headline": { "text": "La afirmación en una línea", "emphasis": ["afirmación"] } },
  "transcript": "media/talk.words.json",
  "write": "projects/clip-01.json"
}

wecut recipe apply --input request.json (o --input - con el JSON en stdin) comprueba todo y guarda el proyecto; luego preview y render lo. Los clips sin role alimentan body; una sección sin clips toma prestado el inicio del metraje del siguiente.

4. Guarda la tuya propia: wecut recipe from-project projects/clip-01.json --name mi-estilo --write recipes/mi-estilo.json mantiene secciones, transiciones, ranuras de texto, estilo de subtítulos, efectos y la música como pista predeterminada.

Música: una receta puede llevar su propia pista (music.src), usada por defecto como la canción en una plantilla de CapCut. Pasa "music": "media/song.mp3" (o un vídeo, cuyo sonido se usa) para reemplazarla, o "none". Una canción tomada del vídeo de otra persona puede ser silenciada por la plataforma después de la subida; añadir un sonido de moda en la aplicación al publicar evita eso.

Copia la estructura, no el contenido: el metraje, las palabras exactas y la música de otros creadores siguen siendo suyos.

Hacer varios clips a partir de un vídeo largo

1. wecut probe la fuente y obtén una transcripción con tiempos de palabras.
2. Lee la transcripción y elige los momentos (tú decides; WeCut no juzga el contenido).
3. Escribe un proyecto por clip, cada uno con captions.src apuntando a la fuente para que una transcripción sirva para todos los clips.
4. wecut preview uno de ellos, ajusta focus, luego wecut render cada uno.

Solución de problemas

• E_RANGE: to está más allá del final del archivo. Usa wecut probe para la duración real.
• E_PATH: la ruta está fuera del espacio de trabajo o es una URL.
• E_MEDIA: el archivo no es un vídeo, imagen o archivo de audio legible, o del tipo incorrecto para ese campo (música en clips, vídeo en overlays).
• E_DEPENDENCY: FFmpeg faltante, anterior a 6, o compilado sin libass. Ejecuta wecut doctor.
• Renderizado demasiado lento: --preset draft, un output.res más bajo, o menos clips por proyecto. render_seconds y realtime_factor en el resultado te indican la velocidad en esta máquina.
• Para ver exactamente qué ejecutará FFmpeg: wecut render project.json --dry-run.