{"_id":"@artemyashin/media-kit","_rev":"2-0c6e48fd929d045bcf25cb3210ca7561","name":"@artemyashin/media-kit","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@artemyashin/media-kit","version":"0.1.0","keywords":["video","image","ffmpeg","frontend","assets","media","optimize","webm","cli"],"license":"MIT","_id":"@artemyashin/media-kit@0.1.0","maintainers":[{"name":"artemyashin","email":"artemyashindev@gmail.com"}],"bin":{"media-kit":"dist/cli.js"},"dist":{"shasum":"88ca706a39ba1fbbbbce8232e6bbc38072026259","tarball":"https://registry.npmjs.org/@artemyashin/media-kit/-/media-kit-0.1.0.tgz","fileCount":170,"integrity":"sha512-K0FkHIJn0D8IDt8zOiR3u8PZsyHAb87DUr9nTAPiYOWMEc2wga2ihArIue8Wu8rRkYyAgXfSZeCWvK9Cpy50Rg==","signatures":[{"sig":"MEUCIEm54YPbV0TvoHq/Y0WF7lTFq7JSUCEPpk3/6xZ6xJd5AiEA0AF2ITs66qyfEa9pIHeI6RWXkDn++SQcZlsgMhc2hTM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":179542},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"22575696681c41d6e6344ff3bef041992eb4acab","scripts":{"build":"tsc","videos":"npm run build && node dist/cli.js video","prepack":"npm run build"},"_npmUser":{"name":"artemyashin","email":"artemyashindev@gmail.com"},"_npmVersion":"10.8.2","description":"CLI toolkit for optimizing, validating, and tracking frontend media assets.","directories":{},"_nodeVersion":"20.19.2","dependencies":{"jiti":"^2.4.2","@inquirer/prompts":"^8.5.2","@ffmpeg-installer/ffmpeg":"^1.1.0","@ffprobe-installer/ffprobe":"^2.1.2"},"_hasShrinkwrap":false,"packageManager":"npm@11.6.2","devDependencies":{"typescript":"^5.8.3","@types/node":"^22.10.2"},"_npmOperationalInternal":{"tmp":"tmp/media-kit_0.1.0_1780912112042_0.349872219294749","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@artemyashin/media-kit","version":"0.1.3","description":"CLI toolkit for optimizing, validating, and tracking frontend media assets.","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"media-kit":"dist/cli.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"license":"MIT","engines":{"node":">=18"},"keywords":["video","image","ffmpeg","frontend","assets","media","optimize","webm","cli"],"packageManager":"npm@11.6.2","scripts":{"build":"tsc","prepack":"npm run build","videos":"npm run build && node dist/cli.js video"},"dependencies":{"@inquirer/prompts":"^8.5.2","ffmpeg-probe":"^1.0.6","ffmpeg-static":"^5.3.0","jiti":"^2.4.2"},"devDependencies":{"@types/node":"^22.10.2","typescript":"^5.8.3"},"_id":"@artemyashin/media-kit@0.1.3","gitHead":"ac4e85caddf2d37cdeaa66aa740fdac789d5bc5b","_nodeVersion":"20.19.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-PqkrHfEuEJ1FnpCBCfUEBNlvQadgxzJBDWPxWCNsAZnXWx3/whnJdRCAn2+IwRd2cc8rLm68eP8ElIu9S2SXzQ==","shasum":"a1196f1ca65a75f92f7ea283478f594fd7510403","tarball":"https://registry.npmjs.org/@artemyashin/media-kit/-/media-kit-0.1.3.tgz","fileCount":71,"unpackedSize":79592,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIE1Yii8Oge2/NqBX4jkWRGLZt4k0enHFchoRn+bynO4LAiBSUGmBcn7Rp7J5+mol+B+N9rJ4HMM1EVUNG1yVYEpQqA=="}]},"_npmUser":{"name":"artemyashin","email":"artemyashindev@gmail.com"},"directories":{},"maintainers":[{"name":"artemyashin","email":"artemyashindev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/media-kit_0.1.3_1780913727483_0.8190022202996641"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-08T09:48:31.826Z","modified":"2026-06-08T10:15:27.774Z","0.1.0":"2026-06-08T09:48:32.169Z","0.1.3":"2026-06-08T10:15:27.628Z"},"license":"MIT","keywords":["video","image","ffmpeg","frontend","assets","media","optimize","webm","cli"],"description":"CLI toolkit for optimizing, validating, and tracking frontend media assets.","maintainers":[{"name":"artemyashin","email":"artemyashindev@gmail.com"}],"readme":"# media-kit\n\nCLI toolkit for optimizing, validating, and tracking frontend media assets.\n\nConverts 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.\n\n## Quick Start\n\n```bash\nnpm install --save-dev media-kit\n```\n\nAdd scripts to `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"videos:optimize\": \"media-kit video optimize\",\n    \"videos:interactive\": \"media-kit video optimize --interactive\",\n    \"videos:validate\": \"media-kit video validate\",\n    \"videos:clean\": \"media-kit video clean\",\n    \"videos:state\": \"media-kit video state\"\n  }\n}\n```\n\nPut a source video in `public/videos-raw` and run:\n\n```bash\nnpm run videos:optimize\n```\n\nUse the generated video in code:\n\n```ts\nimport { getVideoPath } from 'media-kit';\n\nconst src = getVideoPath('hero.webm');\n// => '/videos/hero.webm'\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `media-kit video optimize` | Optimize all raw videos using defaults |\n| `media-kit video optimize <file>` | Optimize one video with inline options |\n| `media-kit video optimize -i` | Choose a video and options interactively |\n| `media-kit video validate` | Check integrity of generated videos, lock, and usages |\n| `media-kit video clean` | Remove stale generated videos and lock entries |\n| `media-kit video state` | Print the current lock file as a table |\n\n### Optimize examples\n\n```bash\n# All videos with defaults\nnpm run videos:optimize\n\n# One video with custom quality\nnpm run videos:optimize -- Hero.mp4 --quality high --no-audio\n\n# Replace an existing generated video\nnpm run videos:optimize -- Hero.mp4 --quality medium --replace\n\n# Interactive mode (prompts for file, quality, transparency, audio)\nnpm run videos:interactive\n```\n\n### Optimize options\n\n| Option | Description |\n|--------|-------------|\n| `--quality <name>` | `tiny`, `low`, `medium`, `high`, `ultra` |\n| `--transparent` | Convert black background to alpha |\n| `--preserve-alpha` | Keep existing alpha channel |\n| `--no-audio` | Strip audio tracks (default) |\n| `--keep-audio` | Keep and re-encode audio as Opus |\n| `--replace` | Overwrite existing generated output |\n| `--interactive`, `-i` | Interactive file/option picker |\n\n### Global options\n\n| Option | Description |\n|--------|-------------|\n| `--config <path>` | Use a custom config file instead of `videos-conf.ts` |\n\n## Configuration\n\nThe package works without any config file. Create `videos-conf.ts` only to override defaults:\n\n```ts\nimport type { VideoConfig } from 'media-kit';\n\nconst config: Partial<VideoConfig> = {\n  usageRoots: ['src', 'stories'],\n  defaultQuality: 'medium',\n};\n\nexport default config;\n```\n\n### Defaults\n\n| Option | Default |\n|--------|---------|\n| `rawDir` | `public/videos-raw` |\n| `outputDir` | `public/videos` |\n| `lockFile` | `videos-lock.json` |\n| `publicBasePath` | `/videos` |\n| `defaultQuality` | `low` |\n| `defaultAudio` | `remove` |\n| `usageRoots` | `['src', 'app', 'pages', 'components', 'index.html']` |\n| `usageExtensions` | `['.css', '.html', '.js', '.json', '.jsx', '.md', '.scss', '.ts', '.tsx']` |\n\n## Quality Presets\n\n| Preset | VP9 CRF | Use case |\n|--------|---------|----------|\n| `tiny` | 52 | Barely visible background textures |\n| `low` | 44 | Most UI/decorative videos (default) |\n| `medium` | 36 | Important visual content |\n| `high` | 28 | Hero sections, marketing assets |\n| `ultra` | 20 | Quality-critical, file size secondary |\n\nLower CRF = higher quality = larger files.\n\n## Project Structure\n\n```text\npublic/videos-raw/       Raw source videos (git-ignored)\npublic/videos/           Generated WebM output (committed)\nvideos-lock.json         Lock file tracking all processed videos\nvideos-conf.ts           Optional config overrides\n```\n\n## Validation\n\n`media-kit video validate` checks:\n\n- Every generated video has a lock entry\n- Every lock entry has a corresponding generated file\n- Every generated video is referenced somewhere in project files\n- Every `getVideoPath('...')` or `/videos/...` usage points to an existing file\n- Lock values use known quality, transparency, and audio modes\n\n## Transparency Modes\n\n| Mode | Flag | Description |\n|------|------|-------------|\n| `none` | (default) | No transparency processing |\n| `screen` | `--transparent` | Convert black background to alpha overlay |\n| `preserveAlpha` | `--preserve-alpha` | Preserve existing alpha channel from source |\n\n## Workflow\n\n### Adding a video\n\n1. Drop source file in `public/videos-raw`\n2. Run `npm run videos:optimize` (or `npm run videos:interactive` for custom settings)\n3. Reference it: `getVideoPath('my-video.webm')`\n4. Run `npm run videos:validate`\n5. Commit generated video + updated lock file\n\n### Reprocessing a video\n\n```bash\nnpm run videos:optimize -- MyVideo.mp4 --quality high --replace\n```\n\n### Removing unused videos\n\n```bash\nnpm run videos:validate   # see what's unused\nnpm run videos:clean      # remove stale files\n```\n\n## Programmatic API\n\n```ts\nimport { getVideoPath, createVideoPathResolver, loadVideoConfig } from 'media-kit';\n\n// Resolve a single video path\ngetVideoPath('hero.webm');\n// => '/videos/hero.webm'\n\n// Create a resolver with a custom base path\nconst resolve = createVideoPathResolver({ basePath: '/cdn/videos' });\nresolve('hero.webm');\n// => '/cdn/videos/hero.webm'\n\n// Load the project config programmatically\nconst config = await loadVideoConfig();\n```\n\n## Limitations\n\n- Validation only detects static string usages (`getVideoPath('...')` and `'/videos/...'`). Dynamic references are not detected.\n- Transparency conversion is best-effort. Screen-mode works well for black-background overlays but may need visual review.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}