Tommy: web assets optimverter

Tommy will process, optimize and convert all your static assets ready to use for the web.

Arguments

• --src specify the source directory (where your assets are located)
• --dst specify the destination directory (where your assets will be generated)

Optional argumenmts

• --force regenerate all assets ignoring cache
• --config specify a JSON file containing an extension to the configuration
• --webserver will spawn an HTTP webserver that access via POST / a request to run
• --port is the webserver port (default: 80)
• --watch will enable a persistent watch over the src directory to detect instant file changes

⚡️️️ Always set --dst option to an empty directory: this directory should only be used by Tommy because files in could be potentially deleted if Tommy is started with a weird configuration or a corrupted database ⚡️

How to: run with Docker

The main advantage of using Tommy is that all dependencies used to process/convert entities are encapsulated into a docker image.

For this reason, you should use the docker run command to use Tommy in the original way it was created.

docker run \
-v "$(pwd)/test/src":/src \
-v "$(pwd)/test/dst":/dst \
-v "$(pwd)/config.json:/root/config.json" \
kopiro/tommy:latest \
--src /src \
--dst /dst \
--config /root/config.json

Explanation of mounts:

• -v "$(pwd)/test/src":/src mount the source directory (where your assets are located) into container /src
• -v "$(pwd)/test/dst":/dst mount the destination directory (where your assets will be generated) into container /dst
• -v "$(pwd)/config.json:/root/config.json" mount your (optional) configuration JSON file into container /root/config.json

How to: run in MacOS

You can also use the native NPM package on OSX.

Installation

npm -g i kopiro-tommy

Run

tommy --src ./test/src --dst ./test/dst

Configuration

By providing a JSON file to --config, you configuration will be extended with the default one.

tommy --config config.json

Example:

{
  "processor.resize": {
    "enabled": false
  },
  "processor.resize": {
    "enabled": true,
    "suffix": "-resized-${i}.${ext}",
    "dimensions": [100, 300],
    "quality": 60
  },
  "ignore": [".dockerignore"]
}

First-level keys

| Key | Type | Description | Default | | ------ | -------- | ----------------- | ----------------- | | ignore | string[] | Pattern to ignore | see config.json |

Available services

Images

| Key | Applies to | Description | | -------------------------- | ------------ | ---------------------------------------------------------------------------------------------- | | processor.resize | * | resize the image in differents formats | | processor.image | * | optimize the image | | processor.lazyLoadBlurried | * | generates a very small blurried image that can be used before loading final image in lazy load | | converter.webp | * | converts to WEBP format | | tester.image | * | generates a sample HTML page to test all differents formats | | processor.jpg | *.jpg | optimizes the JPG using jpegoptim | | processor.png | *.png | optimizes the PNG using pngquant | | processor.gif | *.gif | optimizes the GIF using gifsicle | | processor.svg | *.svg | optimizes the SVG using svgo | | processor.favicon | /favicon.png | generates all images/icons needed in various browsers for the favicon |

Videos

| Key | Applies to | Description | | --------------------- | ---------- | -------------------------------------------------------------------------------------------------- | | processor.poster | * | generates a representative poster image from the video to use as picture before loading the video. | | processor.videoThumbs | * | generates N different thumbs from the video | | converter.webm | * | converts to WEBM format | | converter.h264_mp4 | * | converts to H264 using MP4 container | | converter.av1_mp4 | * | converts to AV1 using MP4 container. currently disabled by default because it's very very slow | | converter.hevc_mp4 | * | converts to HEVC using MP4 container | | tester.video | * | generates a sample HTML page to test all differents formats |

Fonts

| Key | Applies to | Description | | --------------- | ---------- | ----------------------------------------------------------- | | converter.ttf | * | converts to TTF format | | converter.otf | * | converts to OTF format | | converter.eot | * | converts to EOT format | | converter.svg | * | converts to SVG format | | converter.woff | * | converts to WOFF format | | converter.woff2 | * | converts to WOFF2 format | | tester.font | * | generates a sample HTML page to test all differents formats |

Audios

| Key | Applies to | Description | | ------------- | ---------- | ---------------------- | | converter.mp3 | * | converts to MP3 format |

Disabling service

By settings enabled: false in a key, you'll disable that service.

...
"processor.resize": {
   "enabled": false
}
...

Specific configurations for services

processor.resize

| Key | Type | Description | Default | | ---------- | -------- | ------------------------------------------------- | ------------------------ | | dimensions | number[] | Dimensions of resized images in PX (longest side) | [200,400,800,1200] | | quality | number | Quality of images | 80 | | suffix | string | Suffix to Applies to new files | "-resized-${i}.${ext}" |

processor.image

| Key | Type | Description | Default | | ------- | ------ | ---------------- | ------- | | quality | number | Quality of image | 80 |

processor.videoThumbs

| Key | Type | Description | Default | | ------- | ------ | ------------------------------ | -------------------- | | count | number | How many thumbnails extract | 5 | | size | number | Length of longest side | 400 | | quality | number | Quality of image | 80 | | suffix | string | Suffix to Applies to new files | "-thumb-\${i}.jpg" |

processor.lazyLoadBlurried

| Key | Type | Description | Default | | ------ | ------ | ------------------------------ | ----------------- | | size | number | Length of longest side | 10 | | suffix | string | Suffix to Applies to new files | "-blurried.jpg" |

processor.poster

| Key | Type | Description | Default | | ------ | ------ | ------------------------------ | --------------- | | suffix | string | Suffix to Applies to new files | "-poster.jpg" |

processor.favicon

| Key | Type | Description | Default | | ------------- | ------ | --------------------------------------------------------------------------------------- | ----------------- | | webmanifest | object | JSON object to extend for the site.webmanifest. Set to false to disable generation. | see config.json | | browserconfig | bool | Set to false to disable generation of browserconfig.xml | true | | test | bool | Set to false to disable HTML test page (favicon.html) | true | | tileColor | string | Color of the tile for Windows | "#336699" | | themeColor | string | Color of the theme for Chrome Mobile | "#336699" |

convert.{webm,*_mp4}

These are the general settings used for video. You can override manually in every section

| Key | Type | Description | Default | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------- | -------------- | | audioCodec | string | The coded to use for audio | null | | crf | number | The range of the CRF scale is 0–51, where 0 is lossless, 23 is the default, and 51 is worst quality possible. | 23 | | pixelFormat | string | It uses full resolution for brightness and a smaller resolution for color. | "yuv420p" | | mapMetadata | string | Choose to keep/remove metadata | "-1" | | movFlags | string | Movie flags to pass to ffmpeg | "+faststart" | | preset | string | Will provide a certain encoding speed to compression ratio. | "medium" |

converter.webm

| Key | Type | Description | Default | | ---------- | ------ | --------------------- | -------------- | | videoCodec | string | see general section | "libvpx-vp9" |

converter.h264_mp4

| Key | Type | Description | Default | | ---------- | ------ | --------------------- | ----------- | | videoCodec | string | see general section | "libx264" |

converter.av1_mp4

| Key | Type | Description | Default | | ---------- | ------ | ------------------------------------------------------------------------------------------- | -------------- | | videoCodec | string | see general section | "libaom-av1" | | audioCoded | string | see general section | "libopus" | | crf | number | see general section (note: this value is higher due te different scale of this algorithm) | 50 |

converter.hvec_mp4

| Key | Type | Description | Default | | ---------- | ------ | -------------------------- | ----------- | | videoCodec | string | The coded to use for video | "libx265" |

Howto: testing locally

You can use the command npm run test-docker to build the image and test against a test directory.

If you need samples, run npm run download-samples

License

MIT