Installation

System requirements

The program runs on Windows 10 (1903+) / 11, macOS 13+ (Ventura and later) and Linux (recent Debian and its derivatives). At the lower end, an Intel Pentium Gold 7505 or thereabouts (2019 or newer) with hardware decoding will do; 8 GB of memory is ample. A graphics card is not strictly required — the program will start without hardware decoding — but for comfortable work one would want Intel QSV or AMD VCE. On such a machine it quietly drops into a lighter mode: shuttling stays smooth, though playback is shown at a reduced resolution. Should you care how that is arranged, the Architecture section explains it.

For work at full resolution, an Intel Core i7 (6th generation) or AMD Ryzen 5 3600+, 16 GB of memory and a discrete graphics card with H.264/H.265 support are the sensible choices. Here the program works in a hybrid fashion: the proxy is decoded on the CPU, the original file on the graphics card.

Automatic installation

macOS

TapeXPlayer is under active development and has not yet been notarised by Apple — an interim state of affairs, with notarisation to follow once the core has settled. In the meantime macOS will block the program on first launch. The script below installs everything needed and lifts that block for you:

curl -fsSL https://raw.githubusercontent.com/ffbsoffa/TapeXPlayer/stable/install.sh | bash

In brief, the script:

  1. Checks for the dependencies (FFmpeg, SDL2, PortAudio and so on)
  2. Installs any that are missing, by way of Homebrew
  3. Fetches the latest release from GitHub
  4. Unpacks it into /Applications
  5. Clears the quarantine flag (xattr -d com.apple.quarantine)
  6. Marks the file executable

Homebrew is required. Should it be absent, the script will say so.

Windows

The installer (recommended). From the releases page, download the TapeXPlayer-Setup file for your architecture — x64 for ordinary PCs, or ARM64 for ARM tablets and laptops (Windows on Snapdragon, say). Run it and follow the wizard: it lays down shortcuts in the Start Menu and on the desktop, and lists the program under “Add or Remove Programs”.

Or, with a single command — PowerShell, run as administrator:

irm https://raw.githubusercontent.com/ffbsoffa/TapeXPlayer/stable/install.ps1 | iex

The script fetches the program, unpacks it into C:\Program Files\TapeXPlayer, places a desktop shortcut and adds it to the PATH.

Should Windows Defender SmartScreen raise a warning, choose “More info” → “Run anyway”. The program is not yet code-signed; signing is planned once the core has settled.

Linux

On Debian- and Ubuntu-based distributions, take the .deb package for your architecture — amd64 for ordinary PCs, or arm64 — from the releases page, and install it:

sudo dpkg -i tapexplayer_*.deb
sudo apt-get install -f    # settles any missing dependencies

Thereafter the program is to hand from the applications menu, or by typing tapexplayer in a terminal. On other distributions there is a standalone binary — see “Manual installation” below.

Manual installation

macOS

  1. Open the GitHub releases page
  2. Download the macOS archive (…-mac.zip) and unpack it
  3. Drag TapeXPlayer.app into /Applications
  4. Clear the quarantine in Terminal: 
    xattr -d com.apple.quarantine /Applications/TapeXPlayer.app
  5. Launch it from the Applications folder

Should the system still ask for confirmation, open “System Settings” → “Privacy & Security” and click “Open Anyway”.

Windows

If you would sooner not install anything, take the portable edition:

  1. Download the …-portable.zip archive for your architecture (x64 or ARM64) from the releases page
  2. Unpack it wherever suits you
  3. Run TapeXPlayer.exe — every library it needs is already inside, so there is nothing further to install

Should SmartScreen raise a warning, choose “More info” → “Run anyway”.

Linux

Where the .deb does not suit (anything other than Debian/Ubuntu), reach for the standalone binary:

  1. Download TapeXPlayer_linux (x86_64) or TapeXPlayer_linux_arm64 from the releases page
  2. Mark it executable: 
    chmod +x TapeXPlayer_linux
  3. Optionally, place it on the PATH: 
    sudo cp TapeXPlayer_linux /usr/local/bin/tapexplayer

The binary is dynamically linked, so it looks to the system for SDL2, SDL2_ttf, FFmpeg, PortAudio, RtMidi and GTK 3 (the dependency list follows below).

Building from source

The project builds with a plain Makefile — not CMake. The command is make, run from the source/ directory.

Required:

  • A C/C++ compiler (GCC 9+ or Clang 10+); on macOS, the Xcode Command Line Tools (which bring swiftc — the native interface is written in Swift)
  • FFmpeg (libavformat, libavcodec, libavfilter, libavutil, libswscale)
  • SDL2, SDL2_ttf
  • PortAudio
  • OpenSSL
  • RtMidi
  • GTK 3 — on Linux only (the native settings and marker windows)

Optional:

  • Lua — for the extension runner. Where the library is found (pkg-config --libs lua), extension support is switched on automatically; without it the build proceeds just the same, simply without Lua extensions.

Installing dependencies

macOS:

Should the Xcode Command Line Tools not yet be present:

xcode-select --install

Then the dependencies by way of Homebrew (lua is optional — needed only for extensions):

brew install ffmpeg sdl2 sdl2_ttf portaudio openssl rtmidi lua

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install build-essential \
    libavformat-dev libavcodec-dev libavfilter-dev libavutil-dev libswscale-dev \
    libsdl2-dev libsdl2-ttf-dev libgtk-3-dev \
    portaudio19-dev libssl-dev librtmidi-dev liblua5.4-dev

Building

git clone -b stable https://github.com/ffbsoffa/TapeXPlayer.git
cd TapeXPlayer/source
make -j8

The finished executable will appear in the build directory. On macOS, to assemble a self-contained .app bundle with all its libraries, use make bundle.

Checking the installation

  1. Start the program
  2. Open a video file: File → Open (or Cmd+O / Ctrl+O)
  3. Confirm that the video plays and the timecode is shown along the bottom of the screen

Should anything misbehave, do open an issue in the GitHub repository.

Next steps

Previous: About the project Next: Your first analysis