foobar2000-catbox — User Guide

1. Quick Start

foobar2000-catbox is a small Rust command-line utility that receives an image file path on stdin, optionally resizes and/or re-encodes the image, then uploads it to catbox.moe (permanent) or litterbox.catbox.moe (temporary), printing the resulting URL to stdout. It is designed to be piped into from tools like foobar2000 components that emit a file path to album art.

Key features:

• Reads the image file path from stdin — drop-in companion for any automation or media player integration
• Uploads to catbox.moe (permanent) or litterbox.catbox.moe (auto-expiring)
• Optional image resizing: scales down to a power-of-two maximum resolution while preserving aspect ratio
• Optional re-encoding to JPG, PNG, or WebP
• Adjustable JPG quality (1–100)
• Optional catbox user account association via user_hash
• Zero runtime arguments — all settings live in settings.yml next to the binary

Prerequisites: A pre-built binary or Rust toolchain (edition 2021). No additional runtime required.

Run it:

echo "/path/to/cover.jpg" | ./foobar2000-catbox

https://files.catbox.moe/ab1cd2.jpg

Tip

Drop the binary and settings.yml into the same directory and it works immediately with all defaults. No flags, no environment variables needed.

What to try next: See Configuration to set your catbox user hash or enable image resizing.

2. Installation

System Requirements

Install Methods

Pre-built binary

Download the release binary for your platform from the repository releases page. Place foobar2000-catbox (or foobar2000-catbox.exe on Windows) in a directory of your choice. Copy settings.yml into the same directory.

Build from source

git clone https://github.com/realoksi/foobar2000-catbox
cd foobar2000-catbox
cargo build --release

Compiling foobar2000-catbox v1.0.9
Finished release [optimized] target(s) in ...

The binary lands at target/release/foobar2000-catbox. Copy it alongside settings.yml.

Important

The binary looks for settings.yml in the same directory as itself, not the working directory. If the file is missing or unreadable, all settings fall back to their defaults silently — no error is shown.

Post-Install Verification

echo "/path/to/any/image.jpg" | ./foobar2000-catbox

A successful install prints a catbox URL. A network or settings error prints a message to stderr and exits non-zero.

3. Configuration

All configuration lives in settings.yml, placed next to the binary. The file is optional — missing or empty settings use built-in defaults.

Annotated settings.yml:

# Upload target
enable_litterbox: false       # true = litterbox.catbox.moe (temporary), false = catbox.moe (permanent)
litterbox_expire_time: "24h"  # Options: "1h", "12h", "24h", "72h" — only used when enable_litterbox: true

# Image re-encoding
enable_encode: false          # Re-encode the image before uploading
encode_format: "JPG"          # Options: "JPG", "PNG", "WEBP"
encode_format_quality: 80     # 1–100; only applies to JPG format

# Image resizing
enable_resize: false          # Scale down oversized images before uploading
resize_max_resolution:        # Maximum width and height (must be powers of two)
    - 1024
    - 1024

# Catbox account (optional)
# user_hash: "f3c9a4e81d2b76f59e40c8a3d"  # 25-char hash from catbox.moe/user/manage.php

# HTTP
user_agent: "Mozilla/5.0 (X11; Linux x86_64; rv:133.0) Gecko/20100101 Firefox/133.0"

Settings Reference

Note

encode_format_quality only affects JPG output. PNG uses lossless compression. WebP always uses lossless encoding (WebPEncoder::new_lossless).

Warning

resize_max_resolution values must both be powers of two (512, 1024, 2048, etc.) and greater than zero. Invalid values cause startup failure with exit code 2 or 3.

See the Admin Guide for a full configuration reference including validation rules and exit codes.

4. Core Usage

Basic Upload

Pipe any supported image file path to the binary:

echo "/home/user/music/album/cover.jpg" | ./foobar2000-catbox

https://files.catbox.moe/ab1cd2.jpg

The URL is printed to stdout. Errors go to stderr. The binary exits 0 on success.

Supported Input Formats

The image crate auto-detects format from file contents (not extension). Supported formats include JPEG, PNG, and WebP.

Temporary Uploads with Litterbox

Enable litterbox mode to upload images that automatically expire:

enable_litterbox: true
litterbox_expire_time: "1h"   # or "12h", "24h", "72h"

echo "/path/to/cover.png" | ./foobar2000-catbox

https://litter.catbox.moe/xyz789.png

Warning

After the expiry time, the URL becomes permanently invalid. Any system caching litterbox URLs (such as a Discord bot) will display a broken image. Use catbox (enable_litterbox: false) for permanent links.

Resize Before Upload

Reduce bandwidth and storage by downscaling large album art:

enable_resize: true
resize_max_resolution:
    - 1024
    - 1024

Images with either dimension exceeding the limit are scaled down using nearest-neighbor filtering while preserving aspect ratio. Images already within the limit are passed through unchanged.

Re-encode to JPG

Normalize format and reduce file size:

enable_encode: true
encode_format: "JPG"
encode_format_quality: 85

Tip

Combine enable_resize and enable_encode for the smallest possible upload — resize first, then re-encode. Both operations happen in-memory before the upload; the original file is never modified.

5. Common Tasks

Upload album art with your catbox account

Goal: Associate uploads with your catbox.moe account so they appear in your file manager.

Prerequisites: A catbox.moe account. Find your user hash at https://catbox.moe/user/manage.php.

Steps:

1. Open settings.yml.
2. Uncomment (or add) the user_hash line with your 25-character hash:

   user_hash: "f3c9a4e81d2b76f59e40c8a3d"
   

3. Run a test upload:

   echo "/path/to/cover.jpg" | ./foobar2000-catbox
   

4. Verify the file appears in your catbox account at https://catbox.moe/user/manage.php.

If it fails: Check that your hash is exactly 25 characters. A wrong-length hash causes exit code 4 and an error message: user_hash isn't 25 characters (N).

Upload in WebP format

Goal: Upload images re-encoded as lossless WebP.

Steps:

1. Edit settings.yml:

   enable_encode: true
   encode_format: "WEBP"
   

2. Run as normal. The uploaded file will be .webp.

Note

WebP encoding is always lossless regardless of encode_format_quality. The quality setting is silently ignored for WebP and PNG.

Keep uploads temporary (auto-expiring)

Goal: Upload images that auto-delete after a set time.

Steps:

1. Edit settings.yml:

   enable_litterbox: true
   litterbox_expire_time: "1h"
   

2. Run as normal.

Verify: The URL returned starts with https://litter.catbox.moe/.

Pipe from a shell script

#!/bin/bash
ART_PATH="$1"
URL=$(echo "$ART_PATH" | /opt/foobar2000-catbox/foobar2000-catbox)
if [ $? -eq 0 ]; then
    echo "Uploaded: $URL"
else
    echo "Upload failed" >&2
fi

6. Troubleshooting

Error: "path/to/file" doesn't exist.

Cause: The file path received on stdin does not point to an existing file.

Solution:

1. Verify the path is correct and the file exists on disk.
2. Ensure no extra whitespace or newline characters are appended — the tool trims the input line, but the path itself must be valid.

Prevention: Validate the path before piping it to the binary.

Error: Failed to load image from memory

Cause: The file exists but could not be decoded as a supported image format (JPEG, PNG, WebP).

Solution:

1. Confirm the file is a valid image, not a corrupt or non-image file.
2. Try opening the file in another image viewer to confirm it loads.

Error: encode_format_quality is out-of-bounds (N)

Cause: encode_format_quality in settings.yml is outside the range 1–100.

Solution:

1. Open settings.yml.
2. Set encode_format_quality to a value between 1 and 100.

   encode_format_quality: 80
   

Error: resize_max_resolution values must be larger than 0 (W, H)

Cause: One or both resize_max_resolution values is zero.

Solution: Set both values to a positive power-of-two integer:

resize_max_resolution:
    - 1024
    - 1024

Error: both values of resize_max_resolution must be a power-of-two (W, H)

Cause: One or both resize_max_resolution values is not a power of two (e.g. 513 instead of 512).

Solution: Use only power-of-two values: 128, 256, 512, 1024, 2048, etc.

Warning

This validation runs at startup, before any image is read. An invalid settings.yml means no uploads succeed until fixed.

Error: user_hash isn't 25 characters (N)

Cause: The user_hash value in settings.yml is not exactly 25 characters.

Solution:

1. Re-copy your hash from https://catbox.moe/user/manage.php.
2. Confirm the value in settings.yml is exactly 25 characters (no trailing spaces).

Upload network error (curl error on stderr)

Cause: The upload request to catbox.moe or litterbox.catbox.moe failed. This can be a transient network issue, the service being down, or the user-agent being blocked.

Solution:

1. Check outbound HTTPS connectivity to catbox.moe.
2. If the service is down, wait and retry.
3. If repeatedly blocked, try adjusting user_agent in settings.yml.

7. FAQ

Q: Does the tool modify the original image file?

No. All resizing and re-encoding is performed in memory. The original file is read-only and never written to.

Q: What image formats can I upload?

Input: any format the image crate can decode, including JPEG, PNG, and WebP. Output when enable_encode: false: same format as the input. Output when enable_encode: true: the format set by encode_format (JPG, PNG, or WebP).

Q: How do I find my catbox user hash?

Log in at catbox.moe, then visit https://catbox.moe/user/manage.php. Your user hash is shown there. It must be exactly 25 characters.

Q: What happens if settings.yml is missing?

All settings revert to their built-in defaults. The tool runs as if the file contained:

• catbox.moe upload (not litterbox)
• no resizing
• no re-encoding
• empty user_hash (anonymous upload)

Q: What does litterbox_expire_time accept?

Exactly four case-sensitive strings: "1h", "12h", "24h", "72h". Any other value will fail YAML deserialization.

Q: Is WebP encoding lossy or lossless?

Always lossless. The code uses WebPEncoder::new_lossless. encode_format_quality has no effect on WebP output.

Q: Can I use this on Windows?

Yes. The binary is cross-platform. On Windows, provide the file path in the format your shell uses (backslashes or forward slashes both work with Rust's Path).

Q: Where is the settings file looked up?

Always in the same directory as the executable binary, not the current working directory. If you move the binary, move settings.yml with it.