Ken Burns Zoom Refinements (Ping-Pong Loop)

[ffroliva]

PR Description: Ken Burns Zoom Refinements (Ping-Pong Loop)

Summary

This PR introduces a configurable "Ping-Pong" (Zoom In/Out) effect to the image-to-video conversion service. It addresses the limitation of the linear zoom, which can become visually overwhelming on long videos. This feature is fully backward compatible.

Changes

1. API Update: Added two optional parameters to POST /v1/image/convert/video:

   • zoom_effect (string, enum: ["linear", "ping-pong", "loop"]): Defaults to "linear".
   • zoom_loop_duration (number): Optional duration (in seconds) for a full loop cycle. Defaults to video length if not provided.

2. Service Logic:

   • Implemented a Triangle Wave function for the zoompan filter when zoom_effect="ping-pong".
   • z = 1 + ({zoom_speed}*{length}) * (1 - abs(2 * mod(on, loop_frames)/loop_frames - 1))
   • This creates a smooth oscillation between 1.0x and MaxZoom.

3. Backward Compatibility:

   • If zoom_effect is omitted, it defaults to "linear", triggering the original code path.
   • If zoom_loop_duration is omitted, it defaults to the full video length (creating one single cycle for the duration of the video).

Usage Examples

1. Default (Linear Zoom) - Unchanged

{
  "image_url": "https://example.com/image.jpg",
  "length": 5
}

2. Ping-Pong Effect (Full Video)

Zooms in and then out once over the entire duration.

{
  "image_url": "https://example.com/image.jpg",
  "length": 10,
  "zoom_effect": "ping-pong"
}

3. Ping-Pong Effect (Frequency Based)

Oscillates (In -> Out -> In) every 30 seconds.

{
  "image_url": "https://example.com/image.jpg",
  "length": 60,
  "zoom_effect": "ping-pong",
  "zoom_loop_duration": 30
}