Media Processing Workflows

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

Navigate to Media Library

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

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)

Click Watermark Button

Click the Watermark button (stamp icon). This triggers:

A media_jobs record is created:

{
  "operation": "apply_watermark",
  "status": "queued",
  "params": {
    "media_id": "abc-123",
    "position": "bottom-right",
    "opacity": 0.7
  }
}

Job is enqueued to BullMQ media-jobs queue
media-worker picks it up and processes it using ImageMagick or FFmpeg

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)

Download Watermarked File

Once status shows Complete:

Hover over the same media item
Click the Download button (bottom-right in the action strip)
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:

Go to /admin (Directus admin panel)
Navigate to Settings → Project Settings → Files
Upload your watermark logo (PNG with transparency recommended)
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

Open Media Library

Navigate to /app/media.

Filter to Videos

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

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:

Find the most recent video
Queue a create_teaser job
Return the job ID

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)

Download Teaser

Once complete:

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

Teaser Limits by Plan

Plan	Teaser Clips per Month
Starter	0 (blocked — video ops require Creator tier)
Creator	10
Pro	50
Studio	Unlimited

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

Select Media Item

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

Click Compress Button

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

Monitor Job

Check the Active Jobs panel:

Operation: compress
Progress: displays percentage (if available)
ETA: ~5-10s for images, ~20-40s for videos

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

Open Media Library

Go to /app/media.

Click Crop Button

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

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.

Adjust Crop Area (Optional)

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

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

Select Multiple Items

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

Click Batch Actions

A floating action bar appears at the bottom with:

Watermark All (green)
Compress All (violet)
Download All (gray zip icon)

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.

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

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

Job Lifecycle

Error Handling

Job stuck in 'processing' for 10+ minutes

Cause: Worker crashed or Stagehand browser session hung.Fix:

Go to /admin → Media Jobs
Find the stuck job and note the ID
SSH into your server: pm2 restart media-worker
Manually re-queue the job via the dashboard or AI chat

Watermark job failed: 'Logo file not found'

Cause: Watermark logo path is incorrect in server/utils/mediaWorker/watermark.js.Fix:

Upload a watermark logo to Directus Files
Update WATERMARK_PATH in watermark.js
Restart the media worker: pm2 restart media-worker

Video teaser failed: 'FFmpeg error'

Cause: Source video is corrupted or in an unsupported format.Fix:

Download the original video
Re-encode it with FFmpeg: ffmpeg -i input.mp4 -c:v libx264 -c:a aac output.mp4
Re-upload to Genie Helper
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

Usage

Administration

Development

Media Processing Workflows

Available Operations

Watermark

Teaser Creation

Compression

Crop & Resize

Watermarking Content

How Watermarking Works

Applying a Watermark

Watermark Configuration

Creating Video Teasers

Teaser Generation Rules

Creating a Teaser

Teaser Limits by Plan

Compressing Media

Compression Settings

Compressing Files

Cropping & Resizing

Supported Aspect Ratios

Cropping a File

Batch Processing

Batch Watermark Example

Job Status Tracking

Dashboard Job Panel

Directus Admin Panel

Job Lifecycle

Error Handling

Next Steps

Schedule Posts

AI Captions

Plan Limits

​Available Operations

Watermark

Teaser Creation

Compression

Crop & Resize

​Watermarking Content

​How Watermarking Works

​Applying a Watermark

​Watermark Configuration

​Creating Video Teasers

​Teaser Generation Rules

​Creating a Teaser

​Teaser Limits by Plan

​Compressing Media

​Compression Settings

​Compressing Files

​Cropping & Resizing

​Supported Aspect Ratios

​Cropping a File

​Batch Processing

​Batch Watermark Example

​Job Status Tracking

​Dashboard Job Panel

​Directus Admin Panel

​Job Lifecycle

​Error Handling

​Next Steps

Schedule Posts

AI Captions

Plan Limits

Available Operations

Watermarking Content

How Watermarking Works

Applying a Watermark

Watermark Configuration

Creating Video Teasers

Teaser Generation Rules

Creating a Teaser

Teaser Limits by Plan

Compressing Media

Compression Settings

Compressing Files

Cropping & Resizing

Supported Aspect Ratios

Cropping a File

Batch Processing

Batch Watermark Example

Job Status Tracking

Dashboard Job Panel

Directus Admin Panel

Job Lifecycle

Error Handling

Next Steps