Hypershot Documentation Release 0.4.1.Dev1

Hypershot Documentation Release 0.4.1.dev1

Kybernetics Project

Jun 26, 2017

Contents

1 Detailed Contents 3 1.1 Introduction...... 3 1.1.1 What it Does...... 3 1.1.2 How it Works...... 3 1.2 Installation...... 4 1.2.1 Installing the Python Application...... 4 1.2.2 Installing Tools...... 4 1.3 Configuration...... 5 1.3.1 Configuration File...... 5 1.3.2 Image Hosters...... 5 1.3.3 Logging Configuration...... 7 1.4 Usage...... 7 1.4.1 Common Options...... 7 1.4.2 Generating and Uploading Screen Shots...... 8 1.4.3 Uploading Existing Images...... 8 1.5 Templating of Upload Results...... 9 1.5.1 Templating Introduction...... 9 1.5.2 Writing Custom Templates...... 9 1.6 Changelog...... 9

2 Indices & Tables 11

i ii Hypershot Documentation, Release 0.4.1.dev1

The hypershot command line tool creates screen shots of a video ﬁle, and uploads them to an image host. You can also upload existing images, using the same conﬁguration as for the screen shots.

Fig. 1: Demo Terminal Session

This manual is separated into these chapters, they should be read in order: • Introduction describes what hypershot can do for you in more detail. • Installation shows how the application itself and necessary tools are installed. • Conﬁguration explains how you can add image hosting services and other custom settings. • Read Usage to learn about the different ways to call the hypershot command. • If you want to add your own result templates, consult Templating of Upload Results for details. • The Changelog is a timeline of the project’s history, check this after an update for new features and other relevant changes. If you’re a developer, see the GitLab README for some information on working with the source code.

Warning: This project is under development, and not all features described here are implemented yet. So do not be surprised if you just get an error message when you try some things. Consult the Changelog regarding the implementation progress.

Contents 1 Hypershot Documentation, Release 0.4.1.dev1

2 Contents CHAPTER 1

Detailed Contents

Introduction

What it Does

Look at one or more video files, taking screen shots without any human interaction, uploading the results to an image hosting service, and finally produce some text output containing links to the images. That output can be used for posting to forums, blogs, etc. You can also upload existing images, using the same configuration as for the screen shots. hypershot is designed for and tested on Linux, and it is expected and supported to run on Mac OSX (report any issues you might encounter). It might run on Windows, if you use CygWin/Babun, Ubuntu for Windows, or one of the Docker distributions for Windows.

How it Works hypershot looks at a video file using mediainfo, and then decides on the offsets for the screen shots, depending on how many you requested and the duration of the video. It then calls an external script or command to take those screenshots – a default script using mplayer, ffmpeg or avconv is provided. The resulting images are then uploaded to a configured image hoster, and the returned URLs plus the mediainfo data are fed into a templating engine. This way you can generate HTML, BBcode, Markdown, or whatever (text) format you need. Then take the final result and post your screen shots on the web – for your convenience, it’s already in your paste buffer. See Usage for more details, and the following chapter on how to install the necessary software.

3 Hypershot Documentation, Release 0.4.1.dev1

Installation

Installing the Python Application

You can install this software into your user home by using the following commands:

mkdir -p ~/.local/venvs/hypershot&& /usr/bin/pyvenv $_;. $_/bin/activate pip install -U pip pip install -r "https://gitlab.com/kybernetics/hypershot/raw/master/requirements.txt" pip install hypershot

mkdir -p ~/bin&& ln -nfs ../.local/venvs/hypershot/bin/hypershot $_

Doing it this way ensures that the software is installed in isolation not interfering with other apps, and vice versa. It also makes uninstalling very easy, because all ﬁles are contained in a single directory tree. For a global install, do the above as root and replace ~/.local by /usr/local, and also replace the last command by this:

ln -nfs ../venvs/hypershot/bin/hypershot /usr/local/bin

You might need to install pyvenv ﬁrst, on Debian and Ubuntu this is done using sudo apt-get install python3-venv. If your platform does not come with a suitable Python3 package, consider using pyenv to get Python 3.4+.

Installing Tools

For uploading images, the above installation is all you need. Doing screen shots though requires some additional tools to be available on the system you want to use hypershot on. You need to provide mediainfo and at least one of the supported video players. The following describes installation on Debian and derived distros, for others call the native package manager instead of APT. mediainfo and mplayer come pre-packaged starting with Debian Wheezy and Ubuntu Trusty, so just install them like this:

apt-get install mediainfo mplayer2

TODO Is mpv the better option? The shell script bundled with this software is able to also use ffmpeg or avconv. Depending on the type of video ﬁle, these might be able to handle cases mplayer can not, and vice versa, so it’s best to have both. Especially when it comes to HEVC encoded media (also known as x.265), it’s best to have a current ffmpeg version. You can get one from the project’s FFmpeg Static Builds website, which also avoids the problems resulting from the “switch between ffmpeg and avconv and back” game Linux distros played a while ago. To install the git build of ffmpeg, do this:

mkdir -p ~/.local/ffmpeg&& cd $_ wget "https://johnvansickle.com/ffmpeg/builds/ffmpeg-git-64bit-static.tar.xz" tar -xJ --no-same-owner --strip-components=1 -f $(basename"$_" ) ln -nfs $PWD/{ffmpeg,ffmpeg-10bit,ffprobe} ~/bin

Choose another archive from the website for 32bit or ARM machines (Raspberry Pi). If you’re able to become root, install into /opt/ffmpeg and create the symlinks in /usr/local/bin instead. Next you need to provide some Conﬁguration before you can use the software.

4 Chapter 1. Detailed Contents Hypershot Documentation, Release 0.4.1.dev1

Conﬁguration

If just want to get started quickly, drop the example conﬁguration ﬁles into the ~/.config/hypershot directory, as follows: mkdir -p ~/.config/hypershot&& cd $_ curl -sL "https://gitlab.com/kybernetics/hypershot/repository/archive.tar.gz?

˓→ref=master" \ | tar -xvz --strip-components=3 --wildcards' */docs/examples/*.yaml'

Then follow the imgur link, if you want to use that service. Otherwise skip to the Usage chapter.

Conﬁguration File

Configuration is read from the file ~/.config/hypershot/config.yaml (on Linux, following the XDG spec). Only YAML is supported. You can set a different location for the configuration file using --config-dir, the file itself is always called either config.yaml or config.yml. All command line parameters can be given a custom default via either the configutation file or an environment variable. Specifically, HYPERSHOT_CONFIG_DIR can be used to set a different default for the --config-dir option. The lookup order is this (first wins): command line options, environment variables, configuration settings, configuration defaults. To select a named image hosting service (which can be configured as shown in the next section), use either service: ‹name› in the config file, HYPERSHOT_SERVICE=‹name› in the environment, or -s ‹name› on the command line. Any option that takes a value works this way.

Image Hosters

To list all the image hosting services, both provided as defaults and those added via the configuration, call hypershot services. Below you find information on how to configure the built-in imgur service, and how to add others to your configuration. Also see this config.yaml for more examples, using it provides you with the following services:

$ hypershot -c docs/examples services ››› Services ‹‹‹ Name Handler Max. Size Ext Service URL imgbb chevereto 16.0 MiB 1 https://imgbb.com imgur imgur 10.0 MiB 2 https://api.imgur.com lutim file_upload 5.0 MiB 1 https://lut.im malzo chevereto 30.0 MiB 1 https://malzo.com

››› 'Ext'ensions column legend ‹‹‹ Ext Image File Extensions 1 BMP GIF JPEG JPG PNG 2 APNG GIF JPEG JPG PDF PNG TIFF XCF

1.3. Conﬁguration 5 Hypershot Documentation, Release 0.4.1.dev1

imgur

To use the built-in imgur service you need to register with them. Select “Anonymous usage without user authoriza- tion”, which will give you a client ID and a client secret. Add those values to the ~/.netrc ﬁle like this:

machine hypershot:api.imgur.com login ‹CLIENT_ID› password ‹CLIENT_SECRET›

Simple File Upload Sites

If a site basically does a HTML form upload (multipart/form-data), use the file_upload handler. Consider this example for https://lut.im/:

services: lutim: handler: file_upload url:"https://lut.im/" limit: 5M types: [JPG, PNG, BMP, GIF] upload_url:"{url}" headers: Referer:"{url}" data: delete-day: 0 crypt: on files_field_name:"file" response_regex:"[^:]+)://(?P[^/]+)/\ (?P[^\"]+).[^>]*>

You can set the HTTP POST request headers, and add any form data in addition to the file upload field. The name of that field must be given in files_field_name. The provided response_regex is used to scan a HTTP response of type text/html or text/plain, and must contain at least one named group of the form (?P...) – see Python’s Regular Expression HOWTO for more details. Those named groups are available in response, in addition to all the handler’s settings, to build an image_url using the Python string formatter. In case of a JSON response, you can use json instead of response for building your image_url.

Chevereto Sites

A good service powered by Chevereto is malzo.com, because you can use it anonymously and it has a high size limit of 30 MiB. If you want to use an account you have there, the next paragraph shows you how – otherwise leave out the login attribute. Here is an example including user account credentials – these settings go into config.yaml like all other ones:

services: malzo: handler: chevereto url:"https://malzo.com" limit: 30M

6 Chapter 1. Detailed Contents Hypershot Documentation, Release 0.4.1.dev1

types: [JPG, PNG, BMP, GIF] login: .netrc

In this example, the special value .netrc means the username and password are kept separate in the ~/.netrc file, which is commonly used to store credentials for FTP access and similar services. Otherwise, provide login and password in the YAML file directly. So also add this to the ~/.netrc file:

machine hypershot:malzo.com login YOURNAME password KEEP_ME_SECRET

This ﬁle must be private, therefor call chmod 0600 ~/.netrc after you initially create it.

Logging Conﬁguration

The Python logging system can be configured by one of the files logging.yaml, logging.yml, or logging. ini. They must be located in the configuration directory, and are checked in the mentioned order. Consult the Python Guide and the Logging How-To for details on the logging machinery and its configuration. For the YAML files, the dictionary method applies (using dictConfig), see this logging.yaml for a full example. The logging level threshold of the root logger depends on the values of debug (DEBUG) and verbose (INFO) – if neither is set, the level is WARNING.

Usage