Skip to main content
Genie Helper offers 4 core media processing operations powered by the BullMQ media worker. All operations run server-side using ImageMagick (images) and FFmpeg (video/audio).

​
Available Operations

Watermark

Apply your logo/signature to images and videos (ImageMagick + FFmpeg overlay)

Teaser Creation

Auto-generate 15-30s preview clips from full videos

Compression

Reduce file size without visible quality loss (web delivery optimization)

Crop & Resize

Adjust aspect ratios for platform-specific requirements (1:1, 9:16, 16:9)

​
Watermarking Content

Watermarks are unlimited on all plans — even the free Starter tier. Use them liberally to protect your content.

​
How Watermarking Works

  • Images: ImageMagick composite overlay (PNG with alpha transparency)
  • Videos: FFmpeg -filter_complex overlay (renders watermark into every frame)
  • Position: Bottom-right corner by default (configurable in future updates)
  • Opacity: 70% by default (semi-transparent)

​
Applying a Watermark

1

Navigate to Media Library

Go to /app/media to see your scraped content grid.
2

Hover Over Media Item

Hover over any image or video thumbnail. You’ll see a 4-button action strip appear at the bottom:
  • Crop (blue)
  • Compress (violet)
  • Watermark (green)
  • Download (gray)
3

Click Watermark Button

Click the Watermark button (stamp icon). This triggers:
  1. A media_jobs record is created: 
    {
  "operation": "apply_watermark",
  "status": "queued",
  "params": {
    "media_id": "abc-123",
    "position": "bottom-right",
    "opacity": 0.7
  }
}
  2. Job is enqueued to BullMQ media-jobs queue
  3. media-worker picks it up and processes it using ImageMagick or FFmpeg
4

Monitor Progress

A toast notification appears: “Watermark queued”Watch the job status in the Active Jobs panel (bottom of Media Library page):
  • Queued (gray) → Processing (spinning blue) → Complete (green)
Processing time:
  • Images: ~100ms (near-instant)
  • Videos: ~30s for a 2-minute 1080p clip (depends on length and resolution)
5

Download Watermarked File

Once status shows Complete:
  1. Hover over the same media item
  2. Click the Download button (bottom-right in the action strip)
  3. Browser downloads the watermarked version
Note: The original file remains untouched. The watermarked version is stored as a separate file reference in Directus.

​
Watermark Configuration

Currently, watermark settings are server-side defaults. To customize:
  1. Go to /admin (Directus admin panel)
  2. Navigate to Settings → Project Settings → Files
  3. Upload your watermark logo (PNG with transparency recommended)
  4. Update server/utils/mediaWorker/watermark.js with your logo path and preferences
Roadmap: UI-based watermark editor (drag position, adjust opacity, upload custom logos) is planned for Phase 10.

​
Creating Video Teasers

Teasers are 15-30 second clips extracted from full-length videos — perfect for platform previews, social media promo, or free content samples.

​
Teaser Generation Rules

  • Input: Any video in your scraped_media collection
  • Output: 15-30s MP4 (H.264 + AAC), max 1280x720 resolution
  • Logic:
    • Videos < 30s → entire video is the teaser (no cutting)
    • Videos 30s–2min → first 30s
    • Videos > 2min → middle 30s (to avoid intros/outros)

​
Creating a Teaser

1

Open Media Library

Navigate to /app/media.
2

Filter to Videos

Click the Video filter at the top to show only video content.
3

Select a Video

Hover over a video thumbnail and click the Crop button (this will be renamed to “Teaser” in a future update).Alternatively, use the AI chat widget:
Create a 30-second teaser from my latest OnlyFans video
Genie will:
  1. Find the most recent video
  2. Queue a create_teaser job
  3. Return the job ID
4

Wait for Processing

Teaser creation takes ~30s per video (FFmpeg render time).Monitor in the Active Jobs panel:
  • Job type: create_teaser
  • Status: Processing (with progress bar if available)
5

Download Teaser

Once complete:
  1. The teaser is saved as a new scraped_media record with media_type: 'teaser'
  2. Appears in your Media Library with a Teaser badge
  3. Hover and click Download to save locally

​
Teaser Limits by Plan

PlanTeaser Clips per Month
Starter0 (blocked — video ops require Creator tier)
Creator10
Pro50
StudioUnlimited
Starter plan blocks all video operations to prevent CSAM risk and bandwidth abuse. Upgrade to Creator ($49/mo) to unlock teasers.

​
Compressing Media

Compression reduces file size for faster uploads and platform delivery without visible quality loss.

​
Compression Settings

  • Images: JPEG quality 85, progressive encoding (via ImageMagick)
  • Videos: H.264 CRF 23, AAC 128kbps audio (via FFmpeg)
  • Target: 30-50% size reduction while maintaining visual fidelity

​
Compressing Files

1

Select Media Item

In /app/media, hover over an image or video.
2

Click Compress Button

Click the Compress button (file-zipper icon, violet highlight on hover).
3

Monitor Job

Check the Active Jobs panel:
  • Operation: compress
  • Progress: displays percentage (if available)
  • ETA: ~5-10s for images, ~20-40s for videos
4

Download Compressed Version

Once complete, click Download to save the compressed file.Size comparison:
  • Original: 12.4 MB
  • Compressed: 5.8 MB (53% reduction)
For optimal performance, compress videos during off-peak hours to reduce server load.

​
Cropping & Resizing

Adjust aspect ratios to match platform requirements (Instagram 1:1, TikTok 9:16, YouTube 16:9, etc.).

​
Supported Aspect Ratios

  • 1:1 (Square) — Instagram feed, profile pics
  • 4:5 (Portrait) — Instagram feed
  • 9:16 (Vertical) — TikTok, Instagram Stories, Reels
  • 16:9 (Landscape) — YouTube, Twitter, Reddit

​
Cropping a File

1

Open Media Library

Go to /app/media.
2

Click Crop Button

Hover over a media item and click the Crop button (blue highlight).
3

Select Aspect Ratio

A modal opens with preset ratios:
  • 1:1 Square
  • 4:5 Portrait
  • 9:16 Vertical
  • 16:9 Landscape
  • Custom (enter width × height)
Click your preferred ratio.
4

Adjust Crop Area (Optional)

A preview shows the crop boundaries. Drag to reposition.Click Apply Crop.
5

Download Cropped File

The cropped version is saved and available for download.
Current limitation: Crop modal UI is not yet implemented. The crop button queues a job with default center-crop. UI editor is planned for Phase 10.

​
Batch Processing

Process multiple files at once to save time.

​
Batch Watermark Example

1

Select Multiple Items

In /app/media, hold Shift and click multiple thumbnails to select them (checkbox appears in top-left of each).
2

Click Batch Actions

A floating action bar appears at the bottom with:
  • Watermark All (green)
  • Compress All (violet)
  • Download All (gray zip icon)
3

Click 'Watermark All'

This creates one media_jobs record per selected item, all with operation: 'apply_watermark'.All jobs are enqueued to BullMQ in parallel.
4

Monitor Job Queue

The Active Jobs panel shows all queued jobs. BullMQ processes them concurrently (up to 5 at a time by default).Total time: ~5-10 minutes for 100 images, ~30-60 minutes for 50 videos.
Batch actions are not yet implemented in the UI. You can manually queue jobs via the AI chat widget:
Watermark all images in my OnlyFans media library
Genie will use the media-process Action flow to queue them.

​
Job Status Tracking

All media operations create media_jobs records in Directus. You can monitor them in:

​
Dashboard Job Panel

At the bottom of /app/media, you’ll see:
  • Active Jobs: Currently processing
  • Queued Jobs: Waiting in BullMQ
  • Recent Jobs: Last 10 completed (with success/failure status)

​
Directus Admin Panel

  1. Go to /admin
  2. Navigate to Content → Media Jobs
  3. View all jobs with:
    • Operation type
    • Status (queued, processing, complete, failed)
    • Error messages (if failed)
    • Job parameters (JSON)

​
Job Lifecycle

​
Error Handling

Cause: Worker crashed or Stagehand browser session hung.Fix:
  1. Go to /admin → Media Jobs
  2. Find the stuck job and note the ID
  3. SSH into your server: pm2 restart media-worker
  4. Manually re-queue the job via the dashboard or AI chat
Cause: Watermark logo path is incorrect in server/utils/mediaWorker/watermark.js.Fix:
  1. Upload a watermark logo to Directus Files
  2. Update WATERMARK_PATH in watermark.js
  3. Restart the media worker: pm2 restart media-worker
Cause: Source video is corrupted or in an unsupported format.Fix:
  1. Download the original video
  2. Re-encode it with FFmpeg: ffmpeg -i input.mp4 -c:v libx264 -c:a aac output.mp4
  3. Re-upload to Genie Helper
  4. Retry teaser creation

​
Next Steps

Schedule Posts

Queue processed media for automated publishing

AI Captions

Generate captions for your watermarked content

Plan Limits

Check your remaining watermark/teaser quota

Build docs developers (and LLMs) love

Get started for freeTalk to us