Squishy User Guide

This guide will walk you through using Squishy to transcode and manage your media files.

Getting Started

After installing and configuring Squishy, you can access the web interface by navigating to http://your-host:5101 in your browser.

Onboarding Wizard

When you first access Squishy, you'll be guided through an onboarding wizard to configure your setup:

1. Welcome: Introduction to Squishy

   

2. Media Source: Configure Jellyfin or Plex integration

   

3. Media Libraries: Select which libraries to include

   

4. Path Configuration: Set up paths for media and transcoded files

   

5. Library Scan: Perform initial scan of your media library

   

6. Transcoding Presets: Choose preset collections (Quality or Compatibility)

   

7. Hardware Acceleration: Detect and configure hardware acceleration

   

8. Completion: Finish setup and start using Squishy

Congratulations, you've made it through the onboarding wizard!

Media Source Configuration

Choose between Jellyfin and Plex:

• Jellyfin:

  • Enter Jellyfin URL (e.g., "http://jellyfin:8096")
  • Enter API key (found in Jellyfin Dashboard → Advanced → API Keys)

• Plex:

  • Enter Plex URL (e.g., "http://plex:32400")
  • Enter Plex token (can be obtained from Plex logs or authenticated requests)

Media Libraries

Select which libraries from your media server should be included in Squishy. Only enabled libraries will be scanned and displayed.

Path Configuration

Set up the following paths:

• Media Path: Path to your media files inside the Squishy container
• Transcode Path: Where transcoded files will be stored
• Path Mappings: Map paths between your media server and Squishy
• FFmpeg Path: Path to FFmpeg executable (usually "/usr/bin/ffmpeg")
• Concurrent Jobs: Maximum number of simultaneous transcoding jobs

Hardware Acceleration

Squishy will detect available hardware acceleration methods on your system. Currently, it supports:

• VA-API: For Intel GPU hardware acceleration

Main Interface

After completing the onboarding, you'll see the main interface with your media library.

Browse Media Library

The home page displays your media organized by type (Movies and TV Shows):

• Movies: Browse your movie collection with poster art
• TV Shows: Browse your TV series collection organized by show and season
• Search: Find specific titles quickly

Media Details

Clicking on a media item shows its details:

• Title and Metadata: Year, duration, and other information
• Available Versions: List of existing transcoded versions
• Transcode Options: Start a new transcode with different presets

Transcoding Job Management

The Jobs page shows:

• Active Jobs: Currently running transcoding jobs with progress
• Pending Jobs: Jobs waiting to be processed
• Completed Jobs: Successfully transcoded media
• Failed Jobs: Jobs that encountered errors

You can:

• Cancel Jobs: Stop a running or pending job
• View Logs: See detailed FFmpeg output for troubleshooting
• Delete Jobs: Remove completed or failed jobs from the list

Downloading Transcoded Media

Once a transcode is complete, you can:

• Download: Download the transcoded file directly to your device
• Stream: Play the media in your browser
• Get Link: Copy a direct download link to use in other apps

The download link can be used in any browser or media player app that supports direct URL playback.

Administration

The Admin interface provides additional management options:

Preset Management

• View Presets: See all available transcoding presets

  

• Add/Edit Preset: Create and edit custom presets with specific settings

  

• Delete Preset: Remove unused presets

Settings

• Scan Library: Manually trigger a media library scan
• Hardware Settings: Adjust hardware acceleration configuration
• Path Configuration: Modify paths and mappings
• Maximum Jobs: Change the concurrent jobs limit

Best Practices

1. Preset Selection:

   • Use "high" or "medium" quality for tablets and larger devices
   • Use "low" or "potato" quality for phones or limited bandwidth

2. Hardware Acceleration:

   • Enable hardware acceleration for faster transcoding
   • Set allow_hw_failover: true for better reliability

3. Concurrent Jobs:

   • Set based on your CPU/GPU capabilities
   • Too many concurrent jobs may slow down your server

4. Container Selection:

   • Use MP4 for maximum compatibility
   • Use MKV for better quality and flexibility

5. Codecs:

   • H.264 for maximum compatibility
   • HEVC for better quality at smaller file sizes (modern devices only)

Troubleshooting

• Transcoding Fails: Check the job logs for specific error messages
• Hardware Acceleration Issues: Verify device permissions and driver compatibility
• Media Not Found: Check path mappings between media server and Squishy
• Slow Transcoding: Reduce concurrent jobs or check resource utilization