Skip to content
This repository has been archived by the owner on Oct 4, 2023. It is now read-only.

☕ A lightweight tool for quick and easy video compression under a size limit

License

Notifications You must be signed in to change notification settings

MarcusCemes/little-espresso

Repository files navigation

Little Espresso

An example with the command line

Features

  • 🎬 High quality video compression - uses the best encoder settings available
  • 📈 Two-pass encoding - for the best possible data distribution
  • 📦 Zero configuration - works right out of the box
  • ✂️ Cross platform - it could probably even work on your phone
  • 🔥 Uses a powerful industry-standard video encoder
  • 😊 Friendly experience - telling you what's going on, from start to finish

Why?

Sharing pictures is a blast. What if you want to share video? Ever hit that file size limit when sending an email? How about you want to share a video extract with someone over Skype? Today, we're surrounded by movie content, yet the hidden difficulty of streaming such vast quantities of data often go unnoticed. Platforms like YouTube make it look easy, that's if you don't mind advertisements, tracking and inappropriate "recommended videos". In 2016, 73% of all internet traffic was video content, and it's only going to rise. It's hands-down the biggest space eater on the internet.

The go-to solution for sharing video is... Upload it to Google Drive, Dropbox, or any other file host! While this is a fantastic solution for high quality content, it's often unnecessary. I've downloaded gigabytes from Google Drive in Adobe ProRes format for a two minute video, because they guy didn't know a thing about video formats.

Little Espresso makes it easy, with its main focus being on compressing within a certain size limit, such as those imposed by email platforms, while retaining the best quality possible! All videos are encoded at the slowest (but best!) preset with two-pass encoding by default.

Getting started

The simple version (for advanced users)

Advanced installation

I know what I'm doing, just hurry up!

Install Node.js and FFmpeg, and then run

npm i -g little-espresso

The following example uses NVM, which is the recommended way of installing Node.js

# Install FFmpeg
$ sudo apt update
$ sudo apt install ffmpeg

# Install NVM
$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash

# RESTART TERMINAL

# Install the latest version of node
$ nvm install node
$ nvm use node

# Install little-espresso
$ npm i -g little-espresso

# Now you can use it!
$ cd /home/videos/
$ little-espresso [options] <paths ...>

This is an example installation for Ubuntu. This depends of course on what platform you're using.


The equivalent of running little-espresso when installed locally is node node_modules/little-espresso/bin/parse-cli.js. The Node.js module itself exposes a function that can be used to start Little Espresso. The API for this documented in a Typescript Definitions file (index.d.ts);

// Import the function, options interface and the error response interface
const littleEspresso, { ProgramParameters, SpiltEspresso } = require('little-espresso');
const result = littleEspresso({
  resolution: 720,
  framerate: false
});

framerate: false is the same as doing --no-framerate. It will not be touched.


😎 The Easy way

The easiest way is to download the executable program from the releases page. This is a single executable file that can be placed in any directory. You may either double-click on it to convert everything in the folder at once, or drag-and-drop a file onto the executable. You will still need to install FFmpeg. The good news is you can just place the downloaded ffmpeg.exe (or just ffmpeg for macOS) and ffprobe.exe into the same folder where you put Little Espresso. For a more complete installation, see The Hard way.

😬 The Hard way

The hard part is installing Node.js and FFmpeg. Little Espresso is can be installed with a single line.

Prerequisites

Little Espresso has two dependencies. Node.js and FFmpeg. Node.js is a fantastic runtime environment that's being used by NASA and many, many others. It's built with the language that powers the web, and it's also the only way to get npm, the dominant package manager for web-related things, and the best way to install Little Espresso. FFMpeg is the most famous free video utility out there. It's great!

drawing Windows

Node.js comes with an installer. FFmpeg is more complicated. You will need to download the binaries (latest version, 64-bit, static). For a quick and dirty solution, place the ffmpeg.exe and ffprobe.exe executables in the same folder as the videos you will be converting, however it is recommended to place them somewhere permanent, and then add the location to PATH.

drawing macOS

Node.js comes with an installer. For FFmpeg, it's recommended to install it using HomeBrew. To install Homebrew, visit https://brew.sh, it's very easy. Once that's done, run:

$ brew install node
$ brew install ffmpeg

Node.js can also be installed with Homebrew, it avoids having to use sudo

drawing Linux

You guys know what you're doing. You're playing with big boy stuff.


Installation

Open up a terminal. On Windows, it's called cmd.exe, and on macOS it's Terminal.app. Run the following line of code:

$ npm i -g little-espresso

That's it! This installs Little Espresso globally. The npm command comes bundled with Node.js!

Uninstalling

You may completely uninstall at any time with:

npm rm -g little-espresso

FFmpeg and Node.js are more difficult to uninstall. Ask Google.

Usage

For the easy way users, double-click on the executable, or drag-and-drop a video file onto it. For the hard way users, you may either use one of the provided scripts or you can take advantage of Little Espresso's full potential using command line. Open a new terminal window, and type the following:

$ cd /path/to/your/videos
$ little-espresso

The syntax is equivilent on Windows, macOS and Linux, however the path system may vary


Little Espresso will guide you through the rest with an interactive experience, which can be overridden with command line parameters.

A simpler option for hard-way-users

You can find a quick launch script in the releases section. Download the script for your OS and place it somewhere where there are videos to convert. Double click on the script, and boom! No need to open terminal! It does it all for you!

Command line options

Little Espresso is customizable. You can see a full list of the available flags by running little-espresso --help. Unless explicitly specified, all job-related parameters will be prompted to the user. Full automation may be achieved by using the -r, -f, -s, -e, -t and -F flags.

Usage: little-espresso [options] <paths ...>

Option What it does
-r, --resolution Specify the resolution for all files
-f, --framerate Specify the framerate for all files
-s, --start Specify the start time for all files
-e, --end Specify the end time for all files
--no-resolution Disable resolution operations
--no-framerate Disable framerate operations
--no-start Disable start-trimming operations
--no-end Disable end-trimming operations
--ffmpeg Full path to FFmpeg binary
--ffprobe Full path to FFprobe binary
-p, --preset Change the H264 encoding preset (default: veryslow)
-t, --target The target file size (default: 8MB)
-h, --help Show this help menu
-V, --version Show the program version
-F, --force Overwrite without asking
--quiet Disable the bell at the end

Example

$ little-espresso -r 720 -f 30 -s 00:00:05 -e 00:00:10 -t 100MB -F --preset medium "../Videos/Clips" "../OtherStuff/video.mp4"

The ../Videos/Clips/ folder will be recursively scanned for videos, and ../OtherStuff/video.mp4 will also be added to the list. Every found video will be downscaled to a vertical resolution of 720, a framerate of 30, trimmed down to a duration of 5 seconds (00:00:05 → 00:00:10), and encoded with a bitrate to fall just under the 100MB target using the medium preset.

If no paths are specified, the Current Working Directory (.) is used.

$ little-espresso
$ little-espresso .
$ little-espresso ./

These three lines are equivalent, they all launch Little Espresso in the current directory

Some things to note

  • If the given resolution is higher than the source content, the source resolution will be used.
  • if the given framerate is higher than the source content, the source framerate will be used.
  • For time trimming, auto may be used to keep the original start/end time.
  • A trim interval beyond the video's timecode may produce an empty file, or just a single frame. No errors are thrown.
  • Compression accuracy will depend on a lot of factors, incluiding the encoding preset and time constraints.

Built With

  • NodeJS - Powered by Chrome's V8 Javascript engine
  • FFmpeg - Does anything you want, as long as it's related to video processing
  • Chalk - A beautiful colour library
  • Inquirer.js - A fantastically intuitive user prompt library

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

License

This project is licensed under the Apache 2.0 License - see the LICENSE.md file for details

TODO