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