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 file, and uploads them to an image host. You can also upload existing images, using the same configuration 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. • Configuration 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 files 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 first, 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 file, 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 Configuration before you can use the software. 4 Chapter 1. Detailed Contents Hypershot Documentation, Release 0.4.1.dev1 Configuration If just want to get started quickly, drop the example configuration files 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. Configuration 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, configura- tion 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 configura- tion. 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. Configuration 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 file 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:"<a href=.(?P<scheme>[^:]+)://(?P<domain>[^/]+)/\ (?P<image>[^\"]+).[^>]*><img class=.thumbnail" image_url:"https://{response[domain]}/{response[image]}" 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<name>...) – see Python’s Regular Expression HOWTO for more details.