asset-optimiser
Optimise images (PNG via oxipng, JPEG via mozjpeg) and videos (responsive MP4/WebM variants + poster frames) for faster website loading.
Open source Open in the app JSON README (API)
About
Optimise images (PNG via oxipng, JPEG via mozjpeg) and videos (responsive MP4/WebM variants + poster frames) for faster website loading.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- rajavijayach
- Origin
- gemini
- Category
- ferramentas
- Version
- 2.1.0
- Last push
- 2026-02-25T05:28:11Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
rajavijayach/asset-optimiser
README
# asset-optimiser
A [Gemini CLI](https://geminicli.com) extension that optimises image and video
assets for faster website loading.
- **PNG** → compressed with [oxipng](https://github.com/shssoichiro/oxipng) (lossless)
- **JPEG** → compressed with [mozjpeg](https://github.com/mozilla/mozjpeg) (lossless or lossy)
- **WebP** → generated from both (optional, via `cwebp`)
- **Video** → responsive MP4 + WebM variants from 4K/1080p sources (via `ffmpeg`)
- **Posters** → JPG + WebP poster frames extracted from video (via `ffmpeg`)
Originals are **never modified**. All output goes to a separate output folder.
---
## Prerequisites
| Tool | Purpose | Install |
|------|---------|---------|
| `oxipng` | PNG compression | `brew install oxipng` / `cargo install oxipng` |
| `jpegtran` (mozjpeg) | JPEG lossless | `brew install mozjpeg` / `apt install mozjpeg` |
| `cjpeg` (mozjpeg) | JPEG lossy | bundled with mozjpeg |
| `cwebp` | WebP conversion | `brew install webp` / `apt install webp` |
| `ffmpeg` | Video transcoding | `brew install ffmpeg` / `apt install ffmpeg` |
| `ffprobe` | Video metadata | bundled with ffmpeg |
> **macOS note:** After installing mozjpeg via Homebrew, add it to your PATH:
> `export PATH="/usr/local/opt/mozjpeg/bin:$PATH"`
---
## Install
```bash
gemini extensions install https://github.com/rajavijayach/asset-optimiser
```
Or for local development:
```bash
git clone https://github.com/rajavijayach/asset-optimiser
cd asset-optimiser
npm install && npm run build
gemini extensions link .
```
---
## Usage
### Via Gemini CLI chat
Just ask naturally:
> "Optimise all images in ./public/assets"
> "Generate WebP versions of my PNG files in ./src/images"
> "Create responsive video variants from my hero video"
### Via slash commands
```bash
# Preview what would be processed
/optimise:preview ./assets
# Full production run (prompts for confirmation first)
/optimise:run ./assets
# Check that all required tools are installed
/optimise:check
```
### Via MCP tools directly
```
check_tools — verify required binaries are on PATH
scan_folder — preview files without processing
optimise_assets — run the full optimisation pipeline
```
---
## Configuration
Copy `.asset-optimiser.json` to your project root and edit to your needs.
The file is auto-detected — no extra flags needed.
```json
{
"folder": "./public/images",
"output_folder": "./public/optimised",
"images": {
"mozjpeg": { "mode": "lossless" },
"webp": { "enabled": true }
},
"videos": {
"enabled": true,
"ffmpeg_preset": "slow"
}
}
```
### Profiles
Pass `profile` to the `optimise_assets` tool for common use cases:
| Profile | Description |
|---------|-------------|
| `quick` | Fast run, modest savings |
| `balanced` | **Default** — good balance of speed and compression |
| `max` | Maximum compression, slower (opt-level 6, veryslow preset, WebP on) |
| `images-only` | Skip all video processing |
| `videos-only` | Skip all image processing |
| `ci` | Quiet, fast preset, suitable for CI/CD pipelines |
---
## JPEG Mode Guide
| Mode | Typical saving | Quality impact |
|------|--------------|----------------|
| `lossless` (default) | 10–25% | None — pixel-perfect |
| `lossy` quality 85 | 30–50% | Visually identical |
| `lossy` quality 75 | 50–65% | Slight softening |
---
## Video Resolution Tiers
The extension auto-detects source resolution and generates:
| Source | Generated variants |
|--------|-------------------|
| 4K (≥3840×2160) | 4K MP4, 1080p MP4, 1080p WebM, 720p MP4 |
| 1080p (≥1920×1080) | 1080p MP4, 720p MP4, 720p WebM |
| 720p (≥1280×720) | 720p MP4 |
| Below 720p | Skipped |
Poster frames (JPG + WebP) are extracted from the first second of each video.
---
## Output Structure
```
public/
├── images/
│ ├── hero.png ← original, untouched
│ ├── banner.jpg ← original, untouched
│ └── intro.mp4 ← original, untouched
└── optimised/
├── hero.png ← oxipng compressed
├── hero.webp ← WebP variant (if enabled)
├── banner.jpg ← mozjpeg compressed
├── banner.webp ← WebP variant (if enabled)
├── intro_poster.jpg
├── intro_poster.webp
├── intro_1080p.mp4
├── intro_1080p.webm
└── intro_720p.mp4
```
---
## Development
```bash
npm run build # compile TypeScript
npm run dev # watch mode
npm test # run unit tests
npm run preflight # lint + build + test
```
---
## License
Apache-2.0