Advanced Topics

This page covers advanced topics for Squishy power users and developers.

Metadata Sidecar Files

For each successfully transcoded file, Squishy creates a JSON sidecar file with comprehensive metadata about the transcode. These files are stored alongside the transcoded media with the same name and an additional .json extension.

Sidecar File Content

The sidecar file includes:

{
  "original_path": "/path/to/original/media.mkv",
  "media_id": "a1b2c3d4e5f6",
  "title": "Movie Title",
  "year": 2023,
  "type": "movie",
  "poster_url": "https://example.com/poster.jpg",
  "thumbnail_url": "https://example.com/thumbnail.jpg",
  "preset_name": "720p-medium",
  "completed_at": "2023-08-01T14:30:45.123456",
  "output_size": "1.24 GB",
  "duration": 7223.4
}

For TV shows, additional fields are included:

{
  "show_id": "show123456",
  "season_number": 2,
  "episode_number": 5,
  "show_title": "TV Show Name"
}

Using Sidecar Files

These metadata files are mainly for Squishy to keep track of completed transcode jobs, but they can also provide an integration point for additional tools. It is important to note that Squishy has no database backing it. Instead, Squishy relies on your media server for a content catalog, sidecar files for job history, and a JSON config file for everything else.

Manual Installation

While Docker is the recommended installation method, you can install Squishy manually:

1. Clone the repository
2. Install the required dependencies:

   pip install -e .
   

3. Create and edit a config.json file
4. Run Squishy:

   python run.py
   

Custom Presets

You can create custom presets to fine-tune your transcoding settings:

1. Create a new preset JSON file or modify the existing ones
2. Define your presets following the format in the effeffmpeg documentation
3. Import your presets through the admin interface

Example of a custom preset for extremely low bitrate:

{
  "presets": {
    "ultra-low": {
      "container": ".mp4",
      "codec": "h264",
      "scale": "360p",
      "audio_codec": "aac",
      "audio_bitrate": "32k",
      "bitrate": "250k",
      "allow_fallback": true
    }
  }
}

API Usage

Squishy provides a basic API for advanced integrations. The API endpoints are:

GET /api/media

Returns a list of all media in the library.

GET /api/media/{media_id}

Returns detailed information about a specific media item.

POST /api/transcode

Start a new transcode job:

{
  "media_id": "123456",
  "preset": "high"
}

GET /api/jobs

List all transcoding jobs.

DELETE /api/jobs/{job_id}

Cancel a transcoding job.

WebSocket Events

Squishy uses WebSockets to provide real-time updates on transcoding jobs. The following events are available:

• job_started: A new job has started
• job_progress: Job progress has been updated
• job_completed: A job has completed
• job_failed: A job has failed
• job_cancelled: A job has been cancelled

You can subscribe to these events using JavaScript:

const socket = io();
socket.on('job_progress', function(data) {
  console.log(`Job ${data.job_id} progress: ${data.progress}%`);
});

Monitoring

Squishy logs extensive information about its operations. To view the logs:

docker logs squishy

For more detailed logging, set the environment variable:

environment:
  - LOG_LEVEL=DEBUG

Upgrading

To upgrade Squishy to a newer version:

1. Pull the latest changes:

   git pull
   

2. Rebuild the Docker container:

   docker compose down
   docker compose up --build -d
   

3. Check the logs for any migration messages:

   docker logs squishy
   

Backing Up Configuration

To back up your Squishy configuration:

1. Copy the configuration file:

   docker cp squishy:/config/config.json ./config_backup.json
   

2. (Optional) Back up your custom presets:

   docker cp squishy:/app/squishy/presets ./presets_backup
   

Performance Tuning

For optimal performance:

1. Use hardware acceleration when possible
2. Adjust the max_concurrent_jobs based on your CPU/GPU capabilities
3. Use a fast SSD for the transcodes directory
4. Ensure sufficient network bandwidth between containers