Compressa

Universal media compressor for local folders, explicit individual files, and Google Drive links — zero setup required for local files, optional one-time login for Google Drive.

Features

• Log in to Google Drive once (compressa login), tokens are stored locally and auto-refreshed — no need to create your own API key / OAuth client
• Flexible inputs: Google Drive link (folder/file), local directory, or explicit files — can be combined in a single run
• Recursive Drive folder listing + shortcut resolution, safe pagination for thousands of files
• Parallel downloading with automatic retries on rate limits (429) or 5xx server errors
• Parallel compression per media type:

| Type | Tool | Result | |---|---|---| | JPG/JPEG | ImageMagick | -strip -interlace Plane -quality 80 | | PNG/GIF/WebP/HEIC/etc. | ImageMagick | -strip -quality 80 | | MP4/MOV/WebM/MKV/etc. | FFmpeg | H.264 CRF 28 + AAC 128k, faststart | | PDF | Ghostscript (/ebook) / fallback qpdf | recompressed | | SVG | copied original | unchanged | | Other files | skipped | logged in summary |

• --aggressive mode: iterative encoding until target file size is reached (images ~100 KB, videos ~1 MB)
• Safety guarantee: if the compressed output ends up larger than the original, the original version is automatically retained; for local inputs, original files are never modified
• Animated download progress bar, clear before/after size summary per folder

Installation

npm

npm install -g compressa

AUR (Arch/Manjaro)

PKGBUILD is available in arch/ — push to aur.archlinux.org, then:

yay -S compressa   # or paru / makepkg -si

Source (this repository)

./compressa.sh --help
# or install system-wide to PATH:
sudo make install

Runtime dependencies: bash curl jq file imagemagick ffmpeg ghostscript (optional qpdf).

Windows Support

Compressa supports Windows (Git Bash, WSL, PowerShell, and Command Prompt).

1. Install Node.js & Git for Windows (includes bash):

   winget install OpenJS.NodeJS Git.Git

2. Install media dependencies via winget or chocolatey / scoop:

   winget install ImageMagick.ImageMagick FFmpeg.FFmpeg Artifex.Ghostscript jqlang.jq

3. Install Compressa globally:

   npm install -g compressa

Running compressa in PowerShell, CMD, Git Bash, or WSL will automatically launch the script via bash.exe.

Usage

1. Login (once only, required for Google Drive access)

compressa login

Your browser will open → sign in with any Google account that has access to the target folder/file → copy and paste the code → done. If a warning saying "Google haven't verified this app" appears, click Advanced → Go to App.

Local inputs (folders/files on your computer) do not require login at all.

compressa logout   # remove saved auth token

2. Compress

# Google Drive folder
compressa --url "https://drive.google.com/drive/folders/..." -o ~/output

# Local directory (recursive)
compressa ~/Photos -o ~/Photos-small

# Explicit files
compressa a.jpg b.png video.mp4 -o ./output

# Mixed inputs
compressa ~/Photos --url "https://drive.google.com/file/d/..." -o ./output

# Preview without executing
compressa ~/Photos --dry-run

If no arguments are provided, the script will prompt interactively for input and output.

Flags

| Flag | Description | |---|---| | <local path> / <link> | input items (multiple allowed, can be mixed); local folders expand recursively; max 1 Drive link per run | | --input <path\|link> | explicit input form | | --url <link> | alias for --input targeting Drive links | | -o, --output <path> | destination directory | | --parallel <N> | number of parallel jobs (default: 4) | | --aggressive | iterative compression until target size is reached | | --aggressive-img <B> | aggressive image target size in bytes (default: 102400) | | --aggressive-vid <B> | aggressive video target size in bytes (default: 1048576) | | --dry-run | index and summarize only, without downloading or compressing | | --force | bypass prompt if output directory already exists | | --keep-tmp | preserve temporary working directory | | --debug | verbose log output | | --help | display help message |

Configuration

Edit ~/.config/compressa/compressa.conf:

JPEG_QUALITY=80
CRF=28
PRESET=slow
AUDIO_BITRATE=128k
PARALLEL=4
AGGRESSIVE_IMG_TARGET=102400
AGGRESSIVE_VIDEO_TARGET=1048576

For Application Owners (optional — out of the box usage works immediately)

A bundled credentials.json (Desktop OAuth client) is included in the repository so users don't need to create their own credentials — per-user token.json files remain private in ~/.config/compressa/. If you want to supply custom OAuth credentials (e.g., for your own production app):

1. Open console.cloud.google.com → create or select a project
2. Enable the Google Drive API
3. APIs & Services → OAuth consent screen → External → enter app name + email → set to Production (so any Google account can log in without tokens expiring in 7 days)
4. Credentials → + Create Credentials → OAuth client ID → Application type: Desktop app → Download JSON → save as credentials.json in the repository

Note: Unverified Google apps are limited to ~100 users and present a warning during consent until verified. Alternative credential locations: set the COMPRESSA_CREDENTIALS environment variable or save to ~/.config/compressa/credentials.json.

Testing

./tests.sh

Troubleshooting

| Symptom | Solution | |---|---| | credentials.json not found | Installation broken — ensure credentials.json is included, or set COMPRESSA_CREDENTIALS to its path | | Token rejected (401 / invalid_grant) | Run compressa login to re-authenticate | | File failed due to "scanning" (403) | Newly uploaded Drive files take time to scan; try again later | | Rate limit (429) | Automatically retried with backoff; reduce --parallel if persistent | | Folder not found | Ensure folder is shared with the logged-in account (or Anyone with the link) | | Google-native files (Docs/Sheets) | Automatically skipped — no raw media binary behind them |