Video Poster for Wappler

Generate poster images from local video files in Wappler Server Connect.

The extension extracts a frame from a video and saves it as a WebP or JPEG image. It is available as a native Server Connect action in Wappler Node.js projects.

Features

• Server Connect integration
• Smart, exact-time, percentage, and middle-frame selection
• WebP and JPEG output
• Configurable maximum width and image quality
• Wappler filename templates
• Optional overwrite protection
• Wappler application path and public URL output
• Optional error throwing

Requirements

• Wappler project using the Node.js server model
• Node.js 16 or newer
• Permission to execute child processes and write to the output folder
• Internet access while npm installs the required binaries

Installation

1. Open Project Settings in Wappler.
2. Select Extensions.
3. Click Add Extension.
4. Search for wappler-video-poster.
5. Add the extension and save the project settings.
6. Run Project Updater when prompted.

Wappler installs the required npm modules automatically. A global FFmpeg installation is not required.

The action appears in Server Connect under:

Video > Generate Video Poster

Usage

Add Generate Video Poster after the step that uploads, creates, or copies the source video.

Example configuration:

Video Path:        /storage/videos/example.mp4
Frame:             Smart
Output Folder:     /public/uploads/posters
Filename Template: {name}_poster{ext}
Format:            WebP
Maximum Width:     1200
Quality:           80
Overwrite:         false
Throw Errors:      true

Options

Video Path

The Wappler application path of a local video file.

/storage/videos/example.mp4

Remote URLs and live streams are not supported.

Frame

• Smart selects the middle of videos shorter than two seconds. For longer videos, it selects approximately 10% of the duration, constrained between one and five seconds.
• Exact Time selects a frame at the specified number of seconds.
• Percentage selects a frame at the specified percentage of the video.
• Middle selects the frame at the middle of the video.

Time / Percentage

The value used by the Exact Time and Percentage modes. Percentages must be between 0 and 100.

Output Folder

The Wappler application path where the poster will be saved. The folder is created automatically when it does not exist.

/public/uploads/posters

Files saved inside /public receive a public URL. Files saved elsewhere return an empty url value.

Filename Template

Default:

{name}_poster{ext}

Available placeholders:

• {name} is the source video filename without its extension.
• {ext} is the generated image extension.
• {guid} is a generated unique identifier.

Format

• webp
• jpg

The default format is WebP.

Maximum Width

Maximum poster width in pixels. The aspect ratio is preserved and smaller frames are not enlarged. Use 0 to preserve the original width.

The default is 1200.

Quality

Image quality from 1 to 100. The default is 80.

Overwrite

When enabled, an existing file with the same name is replaced. When disabled, Wappler generates a unique filename such as example_poster_1.webp.

Throw Errors

When enabled, an error stops the Server Connect action. When disabled, the action continues and returns the message through its error output field.

Output

A successful action returns:

{
  "path": "/public/uploads/posters/example_poster.webp",
  "url": "/uploads/posters/example_poster.webp",
  "name": "example_poster.webp",
  "format": "webp",
  "timestamp": 3.053,
  "duration": 30.527,
  "width": 1200,
  "height": 675,
  "error": ""
}

| Field | Description | | --- | --- | | path | Wappler application path of the generated poster | | url | Public URL when the poster is saved inside /public | | name | Generated filename | | format | Generated format: webp or jpg | | timestamp | Selected frame position in seconds | | duration | Total video duration in seconds | | width | Generated poster width | | height | Generated poster height | | error | Empty on success; contains the error when Throw Errors is disabled |

When Throw Errors is disabled, a failure returns empty output values and an error message.

Using the Result

Use the public URL in a later Server Connect step:

{{video_poster.url}}

Use video_poster.path when another server-side action needs the generated file.

Supported Videos

The extension supports common video containers and codecs recognized by the bundled FFmpeg build, including MP4, MOV, WebM, MKV, AVI, MPEG, MPEG-TS, FLV, WMV, Ogg, 3GP, and MXF.

Common supported codecs include H.264, H.265/HEVC, AV1, VP8, VP9, MPEG video, ProRes, DNxHD, Theora, WMV, and MJPEG.

The source must contain a readable video stream with a detectable duration. DRM-protected, encrypted, corrupted, and incomplete videos may not work.

Dependencies

• ffmpeg-static extracts the selected video frame.
• @derhuerst/ffprobe-static reads the video duration and dimensions.
• sharp resizes and encodes the poster image.

Wappler installs the required dependencies automatically.

FFmpeg and ffprobe download binaries for the operating system and CPU running npm. Install dependencies on the deployment target or inside its Docker image; do not copy node_modules between different operating systems or CPU architectures.

License

This extension is available under the MIT License.

Third-party dependencies retain their own licenses. The FFmpeg and ffprobe binary packages are distributed under GPL-3.0-or-later, and Sharp is distributed under Apache-2.0.