Skip to main content

Media Toolbox User Manual

Overview​

Media Toolbox is a desktop app for building and running repeatable media workflows with FFmpeg.
You can run quick one-off jobs, create reusable templates, and automate multi-step processing with watch folders.

This manual explains each screen, function, and option with step-by-step instructions. If a feature is not available on your platform, the app will hide or disable it.

Quick Start​

  1. Launch Media Toolbox.
  2. Go to Tasks.
  3. In Template, choose a default template (for example, Transcode).
  4. Click Add Files and select one or more media files.
  5. If the template requires an output folder, choose one.
  6. Click Run to queue the tasks.
  7. Watch progress in the queue. Click a task to view its log and output path.

Quick Start - Run Task view

Quick tips:

  • Default templates are a safe starting point.
  • You can duplicate a template later to tune settings for your own workflow.
  • The Logs view is usually the fastest way to understand any failure.

Interface Tour​

Tasks​

The Tasks screen is your queue and history view.

Common actions:

  • Template: Choose which template will be applied to the selected files.
  • Add Files: Select input files to create tasks.
  • Remove: Remove selected tasks from the queue.
  • Up/Down: Reorder queued tasks (does not affect running tasks).
  • Run: Queue tasks and start them if Auto Start is enabled.
  • Pause Queue: Prevent new tasks from starting.
  • Resume Queue: Allow tasks to start.
  • Cancel: Stop the currently running task or cancel queued tasks.
  • Clear: Remove completed or failed tasks from view.

Queue status:

  • Queued: Waiting to start.
  • Running: Actively processing.
  • Completed: Finished successfully.
  • Failed: Finished with errors.
  • Canceled: Stopped by user action.

Task Queue status list

Templates​

Templates define how tasks run. You can create new templates or clone defaults.

Common actions:

  • New Template: Create a template from scratch.
  • Duplicate: Copy an existing template as a starting point.
  • Edit: Change template options.
  • Delete: Remove a custom template.

Notes:

  • Default templates are read-only. Duplicate them to customize.
  • Advanced FFmpeg arguments are optional and should be used carefully.

Template editor Template library

Watch Folders​

Watch folders automatically trigger pipelines when new files appear.

Common actions:

  • New Watch Folder: Create a folder watcher and pipeline.
  • Edit: Update the path, pipeline steps, or stability timing.
  • Enable/Disable: Toggle individual watch folders on or off.
  • Run Now: Manually scan the folder once.

Watch folders and pipeline steps

Logs​

Logs show live output from running tasks and system events.

Common actions:

  • Save Logs: Write a snapshot file for support or audits.
  • Clear Logs: Remove visible log lines (does not delete log files on disk).

Logs view

Settings​

Settings control app behavior, paths, and performance.

Common actions:

  • Browse: Pick a file or folder path.
  • Reset to Packaged: Use the bundled FFmpeg tools.
  • Save: Apply setting changes.

Settings screen

Running Tasks​

Use the Tasks screen for one-off processing.

Step-by-step:

  1. Open Tasks.
  2. In Template, select a template.
  3. Click Add Files and select files.
  4. (Optional) Set an output folder if the template supports it.
  5. Review template options (bitrate, delete source, verification).
  6. Click Run.
  7. If Auto Start is off, click Resume Queue.
  8. Select a task to view details and logs.

Notes:

  • Each file becomes its own task in the queue.
  • You can drag and drop files directly into the task list.
  • You can queue tasks while others are running.

Task Templates​

Templates define input, output, and processing rules. Each template belongs to a type. The template editor displays fields based on the selected type.

Common template fields:

  • Name: Label shown in the template list.
  • Description: Short summary shown in the UI.
  • Output Folder: Where outputs are written (if applicable).
  • Delete Source on Success: Remove the original file after success.
  • Verify Output: Run FFprobe to validate output properties.

Transcode​

Encodes a file using FFmpeg.

Typical options:

  • Output Folder: Where the encoded file is saved.
  • Container/Extension: Target extension (for example, .mp4).
  • Bitrate: Target bitrate for video and/or audio.
  • Bit Depth: Output bit depth (if supported by the codec).
  • Hardware Acceleration: Prefer GPU encoders when available.
  • Delete Source on Success: Remove original after a successful encode.
  • Verify Output: Run FFprobe and log basic details.

Step-by-step:

  1. Create or duplicate a Transcode template.
  2. Set a Name and Output Folder.
  3. Choose output settings (container, bitrate, bit depth).
  4. Enable Hardware Acceleration if desired.
  5. Save the template.
  6. Apply the template to files in Tasks and click Run.

Segment​

Splits a video into regions or segments and encodes each output.

Typical options:

  • Regions: One or more crop regions.
  • Coordinates: Pixel or normalized (0-1) coordinates.
  • Output Pattern: File naming pattern for each segment.
  • Delete Source on Success: Ignored when multiple outputs are created.

Step-by-step:

  1. Create or duplicate a Segment template.
  2. Add regions with coordinates (pixel or normalized).
  3. Set an output pattern so each segment is uniquely named.
  4. Save the template.
  5. Run from Tasks.

Distribute​

Copies a file to Hive player targets.

Typical options:

  • Target Rules: Rules that map filename patterns to targets.
  • Multicast: Broadcast once to multiple targets (if supported).
  • Replace Index: Overwrite a numbered slot when filenames start with a number.

Step-by-step:

  1. Create or duplicate a Distribute template.
  2. Add one or more Target Rules (pattern + target list).
  3. Enable Multicast if you want broadcast behavior.
  4. Enable Replace Index if you use numbered filenames.
  5. Save the template.
  6. Apply the template to files or use it in a pipeline.

Delete File (Pipeline Only)​

Deletes the original source file after upstream tasks complete.

Step-by-step:

  1. Add Delete File as the last step in a watch folder pipeline.
  2. Confirm it is after any steps that require the source file.
  3. Enable the watch folder.

Get File Info​

Runs FFprobe and writes media details to the log.

Step-by-step:

  1. Create or duplicate a Get File Info template.
  2. Run it from Tasks or in a pipeline.
  3. Review the log output for media details.

Advanced FFmpeg Args​

Custom templates can include a JSON array of FFmpeg arguments.

Usage tips:

  • Use when you need full control of FFmpeg flags.
  • Validate the arguments on a sample file first.
  • Keep the JSON array in the order FFmpeg expects.

Watch Folders and Pipelines​

Watch folders continuously scan for files and queue workflows automatically.

How it works:

  1. Choose a folder.
  2. Add pipeline steps (templates).
  3. Set Stability Seconds (how long a file must stay unchanged).
  4. Enable the watch folder.

Step-by-step:

  1. Open Watch Folders.
  2. Click New Watch Folder.
  3. Select a Path to monitor.
  4. Add pipeline steps in the desired order (for example, Transcode -> Distribute -> Delete File).
  5. Set Stability Seconds to a value that fits your ingest speed.
  6. Click Save and toggle Enabled.

Pipeline behavior:

  • Each step receives the output of the previous step.
  • If a step fails, downstream steps do not run.
  • If a file changes after being processed, it can be re-queued once it stabilizes again.

Tips:

  • Use Distribute -> Delete File to push media to players and then remove the source file.
  • For multi-step pipelines, verify each template works before chaining.

Distribution (Hive Players)​

The Distribute template sends files to one or more targets.

Target Rules​

Rules match on filename suffix and specify where to send files.

Example rule:

  • Pattern: _gallery.mp4
  • Targets: 10.0.0.20, 10.0.0.21

Behavior:

  • If multiple rules match, all targets are combined.
  • If no rule matches, the file is not sent.

Step-by-step:

  1. Open the Distribute template.
  2. Add a rule with a filename pattern.
  3. Add one or more targets to the rule.
  4. Save the template and test with a sample file.

Multicast Broadcast​

When enabled, the app can use a multicast sender to broadcast once to multiple targets.

Notes:

  • Requires multiple targets.
  • Not available on macOS.
  • Falls back to individual uploads when multicast cannot be used.
  • If rules produce different output filenames per target, multicast is skipped (multicast requires one shared output filename).

Replace Index​

When enabled, a filename that starts with a number is treated as a slot index.

Example:

  • 0150_bees.mp4 targets slot 150.

Use this to overwrite existing media on players by slot number.

Logs and Snapshots​

The Logs view streams live logs from the server.

Step-by-step:

  1. Open Logs.
  2. Scroll to see recent activity.
  3. Click Save Logs to write a snapshot file.
  4. Share the saved file with support if needed.

Storage:

  • Logs are stored in the app data folder under logs/.

Settings​

Key settings you can adjust:

FFmpeg and FFprobe Paths​

Use the bundled tools or point to custom installs.

Step-by-step:

  1. Open Settings.
  2. In FFmpeg Path and FFprobe Path, click Browse.
  3. Select the executable files.
  4. Click Save.

Max Log Entries​

Controls how many log lines are kept in memory.

Step-by-step:

  1. Open Settings.
  2. Set Max Log Entries.
  3. Click Save.

Auto Start​

Automatically start queued tasks.

Step-by-step:

  1. Open Settings.
  2. Toggle Auto Start.
  3. Click Save.

Auto Launch​

Start the app when you log in.

Step-by-step:

  1. Open Settings.
  2. Toggle Auto Launch.
  3. Click Save.

Start Minimized​

Open the app minimized.

Step-by-step:

  1. Open Settings.
  2. Toggle Start Minimized.
  3. Click Save.

Temp Output Folder​

Where temporary outputs are stored.

Step-by-step:

  1. Open Settings.
  2. Set Temp Output Folder.
  3. Click Save.

Clean Temp On Startup​

Remove temp outputs on launch.

Step-by-step:

  1. Open Settings.
  2. Toggle Clean Temp On Startup.
  3. Click Save.

Hardware Acceleration​

Enable hardware encoders when available.

Step-by-step:

  1. Open Settings.
  2. Toggle Hardware Acceleration.
  3. Click Save.

Auto Remove Completed​

Hide completed tasks from the queue list.

Step-by-step:

  1. Open Settings.
  2. Toggle Auto Remove Completed.
  3. Click Save.

Projects (Save/Open)​

The desktop app can save and load full project snapshots.

Save Project​

Step-by-step:

  1. Click File -> Save Project.
  2. Choose a location and filename.
  3. Click Save to write a .htp project file.

Open Project​

Step-by-step:

  1. Click File -> Open Project.
  2. Select a .htp file.
  3. Click Open to restore templates, watch folders, tasks, and settings.

Troubleshooting​

FFmpeg not found​

  • Open Settings and set FFmpeg/FFprobe paths.
  • Use Reset to Packaged if you want bundled defaults.

Watch folder not triggering​

  • Verify the folder path is correct.
  • Ensure the file is stable longer than the Stability Seconds value.
  • Confirm the watch folder is enabled and has at least one pipeline step.
  • Click Run Now to test the watcher.

Distribution failures​

  • Check that target IPs/URLs are reachable.
  • Confirm any firewall rules allow uploads.
  • If multicast fails on macOS, use standard upload targets.
  • Verify filename patterns match the target rules.

Delete File step not working​

  • Place Delete File as the last pipeline step.
  • Ensure the source file is not locked by another process.

Logs too noisy or too short​

  • Increase Max Log Entries.
  • Save a log snapshot before clearing.