media-kit

CLI toolkit for optimizing, validating, and tracking frontend media assets.

Converts raw video files into consistent, web-ready WebM assets with VP9 encoding. Tracks every generated file in a lock file, validates usage across the project, and cleans up stale assets.

Quick Start

npm install --save-dev media-kit

Add scripts to package.json:

{
  "scripts": {
    "videos:optimize": "media-kit video optimize",
    "videos:interactive": "media-kit video optimize --interactive",
    "videos:validate": "media-kit video validate",
    "videos:clean": "media-kit video clean",
    "videos:state": "media-kit video state"
  }
}

Put a source video in public/videos-raw and run:

npm run videos:optimize

Use the generated video in code:

import { getVideoPath } from 'media-kit';

const src = getVideoPath('hero.webm');
// => '/videos/hero.webm'

Commands

| Command | Description | |---------|-------------| | media-kit video optimize | Optimize all raw videos using defaults | | media-kit video optimize <file> | Optimize one video with inline options | | media-kit video optimize -i | Choose a video and options interactively | | media-kit video validate | Check integrity of generated videos, lock, and usages | | media-kit video clean | Remove stale generated videos and lock entries | | media-kit video state | Print the current lock file as a table |

Optimize examples

# All videos with defaults
npm run videos:optimize

# One video with custom quality
npm run videos:optimize -- Hero.mp4 --quality high --no-audio

# Replace an existing generated video
npm run videos:optimize -- Hero.mp4 --quality medium --replace

# Interactive mode (prompts for file, quality, transparency, audio)
npm run videos:interactive

Optimize options

| Option | Description | |--------|-------------| | --quality <name> | tiny, low, medium, high, ultra | | --transparent | Convert black background to alpha | | --preserve-alpha | Keep existing alpha channel | | --no-audio | Strip audio tracks (default) | | --keep-audio | Keep and re-encode audio as Opus | | --replace | Overwrite existing generated output | | --interactive, -i | Interactive file/option picker |

Global options

| Option | Description | |--------|-------------| | --config <path> | Use a custom config file instead of videos-conf.ts |

Configuration

The package works without any config file. Create videos-conf.ts only to override defaults:

import type { VideoConfig } from 'media-kit';

const config: Partial<VideoConfig> = {
  usageRoots: ['src', 'stories'],
  defaultQuality: 'medium',
};

export default config;

Defaults

| Option | Default | |--------|---------| | rawDir | public/videos-raw | | outputDir | public/videos | | lockFile | videos-lock.json | | publicBasePath | /videos | | defaultQuality | low | | defaultAudio | remove | | usageRoots | ['src', 'app', 'pages', 'components', 'index.html'] | | usageExtensions | ['.css', '.html', '.js', '.json', '.jsx', '.md', '.scss', '.ts', '.tsx'] |

Quality Presets

| Preset | VP9 CRF | Use case | |--------|---------|----------| | tiny | 52 | Barely visible background textures | | low | 44 | Most UI/decorative videos (default) | | medium | 36 | Important visual content | | high | 28 | Hero sections, marketing assets | | ultra | 20 | Quality-critical, file size secondary |

Lower CRF = higher quality = larger files.

Project Structure

public/videos-raw/       Raw source videos (git-ignored)
public/videos/           Generated WebM output (committed)
videos-lock.json         Lock file tracking all processed videos
videos-conf.ts           Optional config overrides

Validation

media-kit video validate checks:

• Every generated video has a lock entry
• Every lock entry has a corresponding generated file
• Every generated video is referenced somewhere in project files
• Every getVideoPath('...') or /videos/... usage points to an existing file
• Lock values use known quality, transparency, and audio modes

Transparency Modes

| Mode | Flag | Description | |------|------|-------------| | none | (default) | No transparency processing | | screen | --transparent | Convert black background to alpha overlay | | preserveAlpha | --preserve-alpha | Preserve existing alpha channel from source |

Workflow

Adding a video

1. Drop source file in public/videos-raw
2. Run npm run videos:optimize (or npm run videos:interactive for custom settings)
3. Reference it: getVideoPath('my-video.webm')
4. Run npm run videos:validate
5. Commit generated video + updated lock file

Reprocessing a video

npm run videos:optimize -- MyVideo.mp4 --quality high --replace

Removing unused videos

npm run videos:validate   # see what's unused
npm run videos:clean      # remove stale files

Programmatic API

import { getVideoPath, createVideoPathResolver, loadVideoConfig } from 'media-kit';

// Resolve a single video path
getVideoPath('hero.webm');
// => '/videos/hero.webm'

// Create a resolver with a custom base path
const resolve = createVideoPathResolver({ basePath: '/cdn/videos' });
resolve('hero.webm');
// => '/cdn/videos/hero.webm'

// Load the project config programmatically
const config = await loadVideoConfig();

Limitations

• Validation only detects static string usages (getVideoPath('...') and '/videos/...'). Dynamic references are not detected.
• Transparency conversion is best-effort. Screen-mode works well for black-background overlays but may need visual review.

License

MIT