strm/README.org

* strm

  *strm* is a small Bash script that lets you stream media files over SSH in a convenient way.

  No need for mounting and navigating through complex directory structures anymore.
  Just provide a query and the matching media files are played locally (or remotely) via [[https://mpv.io/][mpv]].

  Here is an example.. let's assume you have the shortfilm [[https://www.dailydweebs.com/][The Daily Dweebs]] stored on a remote machine in the following directory structure:

  #+begin_example
    media
    └── movies
        ├── ...
        ├── The Daily Dweebs (2017)
        │   └── The Daily Dweebs (2017).mkv
        └── ...
  #+end_example

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

  : $ strm daily dweebs

  Every argument which is not assigned to an flag is interpreted as part of the query.
  The query arguments are interpreted as [[https://en.wikipedia.org/wiki/Glob_(programming)][glob patterns]], additionally surrounded by wildcards (=*=).
  If every pattern matches any filepath in the configured media directories, the matched filepaths are interpreted as result.
  The =--or= flag can be set to get results which match at least one pattern.
  Matchings are always done case-insensitive.
  
  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 configured media directories, followed by lexicographical order of the filepath.

  *strm* consists mainly of two parts:

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

  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
   - Play remote files on other machines
   - Synchronize playback positions with remote machines
   - Sleeptimer
     
   You can access your local machine also via SSH, so every occurrence of /remote/ in the list can be replaced with /local/.

** Dependencies

   The dependencies vary, based on the purpose of a machine:

   - The machine shall serve as data storage :: It must be available via SSH.
   - The machine shall serve as player :: [[https://mpv.io/][mpv]] and an SSH client must be installed.
   - The machine shall serve as player and will be remote controlled :: mpv, [[https://github.com/tmux/][tmux]] and an SSH client must be installed, *strm* must be in your path and it must be available via SSH.
   - The machine shall serve as controller :: An SSH client must be installed and *strm* must be executable.

   A machine can be used for multiple purposes, make sure all required dependencies are fulfilled.

   If the =playback_directory= is set, [[https://rsync.samba.org/][rsync]] is used to synchronize it with a local directory.
   
** Installation

   *strm* is just a script, you can execute it directly.
   Or grab it, make it executable and place it in your =$PATH=.

   This project is also a [[https://nixos.wiki/wiki/Flakes][Nix flake]].
   You can execute it with the following command if you have a recent version of [[https://nixos.org/][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

   #+begin_example
     Usage: strm [OPTIONS] QUERIES ... [OPTIONS]

     Stream media files over SSH in a convenient way.

     OPTIONS
       -h, --help                                 Show this help message
       -c, --config CONFIG_FILE                   Path to config file (default:
                                                  ~/.config/strm/strm.config)
       -f, --fullscreen                           Play video files in fullscreen
       -i, --ignore-files IGNORE_FILES            Ignore given filenames
       -l, --list                                 List files instead of playing
       -m, --media-directories MEDIA_DIRECTORIES  Use given media directories,
                                                  config is ignored
       -o, --or                                   Combine queries with a logical OR
                                                  (default: AND)
       -p, --playback-directory DIRECTORY         Use given playback directory
       -q, --quit TIME_IN_MINUTES                 Quit after given time
       -r, --remote SSH_CONNECTION_STRING         Execute strm with other given
                                                  arguments on remote machine (-f is
                                                  set by default)
       -s, --shuffle                              Play files in random order
       -t, --tidy                                 Don't resume playback

     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 glob pattern
                             # 'e*phants'
   #+end_example

   The usual [[https://mpv.io/manual/master/#interactive-control][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.
   - =f= :: Toggle fullscreen.
   - =q= :: Stop playing and quit.
     If the =playback_directory= is configured (or the =--playback-directory= argument ist set), the playback position of the current file is saved on exit and synchronized with the given directory.
     Otherwise the playback position is not saved on exit and nothing is synchronized.

   The last query arguments are saved if a =playback_directory= is set and the =--list= flag is not set.
   If you want to resume playback at a later time, it is sufficient to call =strm= without arguments.
   Use the =--tidy= flag to not resume playback.

   Resuming playback of a file over multiple machines is only possible if all machines are configured with the same =media_directory= path for the file.
   This is due to the fact that mpv stores the playback positions based on the filename hash, which in the case of remote files is the entire file path.
   If you have a decentralized media library, one solution to resume playback everywhere is to use additional hostnames such as =strm-audio= or =strm-video=.
   Then set the IP addresses in the hosts file on every machine accordingly.
   
*** The =--remote= flag

   The =--remote= flag executes *strm* on another machine in a tmux session and passes all other given arguments to it.
   Launching it in a tmux session allows to detach from the session with =C-b d=.
   If a session is already running on the target machine, the session gets attached and further commands are ignored (it is even sufficient to call =strm -r <remote>= to reattach).

   If you pass the =--media-directories= flag, *strm* doesn't need to be configured but make sure your arguments are correct from the point of view of the remote machine.
   The same holds true if you pass the =--config= flag.
   
   =--fullscreen= is inverted when playing on a remote machine.
   It is set by default and not set if you explicitly pass it.

   On the remote, the =$DISPLAY= variable is set by default to =:0= which should fit most setups.
   If you wish to change this, search for the line containing =DISPLAY= in the script and adjust it.

** Configuration

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

   #+begin_src sh
     # 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.
     # Spaces must be escaped with a backslash (\).
     # Media directories are queried and played in order.
     # If <SSH connection string> is not set, 'localhost' is used.
     #
     # Examples:
     #   /home/alice/videos
     #   remote-machine/home/alice/music
     #   bob@another-machine/media/movies,bob@10.0.0.1/home/bob/series
     media_directories=""

     # Directory which contains the saved playback positions of the following form:
     #
     #   <SSH connection string><absolute_path_to_media_directory>
     #
     # It is synchronized with the local ~/.cache/strm directory before and after playing files.
     # If it is not set, the mpv resume playback functionality is not enabled by default.
     # If <SSH connection string> is not set, 'localhost' is used.
     #
     # Examples:
     #   /home/alice/.strm
     #   remote-machine/home/alice/strm
     #   bob@another-machine/home/bob/strm
     playback_directory=""

     # Ignored filenames as comma separated list.
     # This can be glob patterns and matching is done case-insensitive.
     # 
     # Examples:
     #   cover.jpg
     #   *.jpg,*.png
     ignore_files=""
   #+end_src
   
   An example configuration file can be found in the repository.
   
   The default path of the configuration is =$HOME/.config/strm/strm.config=.
   You can use the =--config= flag to set another configuration file.
   
   The flags =--media-directories=, =--playback-directory= and =--ignore-files= are used in favour of configuration parameters and can be used with the same syntax as described above.
   Be aware that if the =--media-directories= flag is given, no configuraion file is loaded (even if explicitly set with =--config=) and thus the configured =playback_directory= and =ignore_files= is not used.
   In this case use additionally the =--playback-directory= and =--ignore-files= flags with the same value from your config file.

   The local directory to which and from which the playback positions are synchronized is =$HOME/.cache/strm=.