strm/README.org

• strm
  • Features
  • Installation
  • Usage
  • Configuration

strm

strm is a small Bash script that lets you stream media files over SSH.

No need for mounting and navigating through complex directory structures anymore. Just provide a query and the media files are played locally via mpv.

Here is an example.. let's assume you have the shortfilm The Daily Dweebs stored on a remote machine in the following directory structure:

  movies
  ├── ...
  ├── The Daily Dweebs (2017)
  │   └── The Daily Dweebs (2017).mkv
  └── ...

If strm is configured to use the movies directory, you can play the shortfilm with e.g. the following command:

  strm daily dweebs

Every argument which is not assigned to a flag is interpreted as part of the query. The query arguments are then surrounded by wildcards (*) and the case gets ignored. If every argument matches any filepath in the configured media directories, the matched filepaths are interpreted as result. The shortfilm from the example above could have also been played with one of the following commands:

  strm dweebs daily
  strm movies dwee
  strm d d 17

It is possible that multiple files are matched by one of the commands. All files are then played in the order of the media directories, followed by lexicographical order of the filepath.

strm consists mainly of two parts:

1. Execute find via SSH on a remote machine
2. Play the matched files with mpv

The rest is just bells and whistles.

Features

• List remote files by query
• Play remote files via mpv
• Query multiple remote directories with one command

You can access your local machine also via SSH, so every occurrence of remote in the list can be replaced with local.

Installation

Make sure, mpv is installed and that you have access to a machine via SSH.

strm is just a script, you can execute it directly. Or grab it and place it in you $PATH.

This project is also a Nix flake. You can execute it with the following command if you have a recent version of Nix installed and flakes are enabled:

  nix run github:Deleh/strm -- --help

If you use it this way, mpv is started with MPRIS support by default.

Usage

  Usage: strm [OPTIONS] QUERY ... [OPTIONS]

  Stream media files over SSH.

  OPTIONS
    -h, --help                                 Show this help message
    -c, --config CONFIG_FILE                   Path to config file
    -l, --list                                 List files instead of playing
    -m, --media-directories MEDIA_DIRECTORIES  Use given media directories, config is ignored
    -s, --shuffle                              Play files in random order

  EXAMPLES
    strm -l .             # List all available files
    strm Elephants Dream  # Play files whose path contain 'elephants' and 'dream'
    strm e*phants         # Play files whose path matches the wildcard 'e*phants'

The usual mpv controls are available while playback. Here is a subset:

LEFT and RIGHT

Seek backward/forward.

p and SPACE

Pause (pressing again unpauses).

< and >

Go backward/forward in the playlist.

q

Stop playing and quit.

Configuration

If the --media-directories argument is not set, the scripts looks for a configuration file with the following content:

  # Media directories on remote machines of the following form:
  #
  #   <SSH connection string><absolute_path_to_media_directory>
  #
  # Multiple media directories can be set with a comma (,) as delimiter.
  # Media directories are queried and played in order.
  #
  # Examples:
  #   localhost/home/bob/videos
  #   remote-machine/home/bob/music
  #   bob@another-machine/media/movies,bob@10.0.0.1/home/bob/series
  media_directories=""

An example configuration file can be found in ./strm.config.

The default path of the configuration is $HOME/.config/strm/strm.config. You can use the --config flag to set another configuration file.

The flag --media-directories is used in favour of a configuration file and can be used with the same syntax as described above.