Lobster

Showcase

https://github.com/justchokingaround/lobster/assets/44473782/d597335c-42a9-4e45-8948-122744aa5ca9

Join the discord server (it is bridged to the matrix space)

https://discord.gg/JTDS2CKjQU

Join the matrix server (I am more active there)

https://matrix.to/#/#lobster-and-jerry:matrix.org

Overview

• Install
  • Arch linux
  • Debian linux
  • Linux
  • Android
  • NixOS
  • Mac
  • iOS
  • Windows
• Usage
  • -c / --continue
  • --clear-history / --delete-history
  • -d / --download
  • --discord / --discord-presence / --rpc / --presence
  • -e / --edit
  • -i / --image-preview
  • -j / --json
  • -l / --language
  • --rofi / --external-menu
  • -p / --provider
  • -q / --quality
  • -n / --no-subs
  • -r / --recent
  • -s / --syncplay
  • -t / --trending
  • -u / -U / --update
  • -v / -V / --version
  • -x / --debug
  • Navigation
• Configuration
• Contributing
• Uninstall

Install

Arch

Note: it is recommended to use the lobster-git package, as it is more up to date, and as the project is currently being actively maintained

paru -S lobster-git

or

paru -S lobster

Debian (using makedeb and mist)

Here are the full installation instructions for Debian:

Install the dependencies:

sudo apt update && sudo apt upgrade && sudo apt install git wget

During this step write makedeb and enter, when prompted:

bash -ci "$(wget -qO - 'https://shlink.makedeb.org/install')"

wget -qO - 'https://proget.makedeb.org/debian-feeds/prebuilt-mpr.pub' | gpg --dearmor | sudo tee /usr/share/keyrings/prebuilt-mpr-archive-keyring.gpg 1> /dev/null

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/prebuilt-mpr-archive-keyring.gpg] https://proget.makedeb.org prebuilt-mpr $(lsb_release -cs)" | sudo tee /etc/apt/sources.list.d/prebuilt-mpr.list

sudo apt update && sudo apt install mist

During this step when prompted to Review files for 'lobster-git'? [Y/n], write n and enter.

mist update && mist install lobster-git

Linux (from source)

sudo curl -sL github.com/justchokingaround/lobster/raw/main/lobster.sh -o /usr/local/bin/lobster &&
sudo chmod +x /usr/local/bin/lobster

Android (requires Termux and mpv-android)

curl -sLO github.com/justchokingaround/lobster/raw/main/lobster.sh &&
chmod +x lobster.sh &&
mv lobster.sh /data/data/com.termux/files/usr/bin/lobster

If you're using Android 14 or newer make sure to run this before:

pkg install termux-am

Nixos (Flake)

Add this to you flake.nix

inputs.lobster.url = "github:justchokingaround/lobster";

Add this to you configuration.nix

environment.systemPackages = [
  inputs.lobster.packages.<architecture>.lobster
];

Or for run the script once use

nix run github:justchokingaround/lobster#lobster

Nixos (Flake) update

When encoutering errors first run the nix flake update command in the cloned project and second add new/missing dependencies to the default.nix file. Use the nixos package search to find the correct name.

nix flake update

Mac

curl -sL github.com/justchokingaround/lobster/raw/main/lobster.sh -o "$(brew --prefix)"/bin/lobster &&
chmod +x "$(brew --prefix)"/bin/lobster

iOS

Install iSH and VLC from the app store.

<summary> Install dependencies: </summary>

apk update; apk add grep sed curl fzf patch

<summary> Install lobster: </summary>

curl -O "https://raw.githubusercontent.com/justchokingaround/lobster/main/lobster.sh"
chmod +x lobster.sh
mv lobster.sh /usr/local/bin/lobster

Windows

<details> <summary>Windows installation instructions</summary>

• This guide covers how to install and use lobster with the windows terminal, you could also use a different terminal emulator, that supports fzf, like for example wezterm
• Note that the git bash terminal does not have proper fzf support

1. Install scoop

Open a PowerShell terminal https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.2#msi (version 5.1 or later) and run:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

2. Install git,mpv and fzf

scoop bucket add extras
scoop install git mpv fzf

3. Install windows terminal (you don't need to have a microsoft account for that) https://learn.microsoft.com/en-us/windows/terminal/install

4. Install git bash (select the option to add it to the windows terminal during installation) https://git-scm.com/download/win

(The next steps are to be done in the windows terminal, in a bash shell)

5. Download the script file to the current directory

curl -O "https://raw.githubusercontent.com/justchokingaround/lobster/main/lobster.sh"

6. Give it executable permissions

chmod +x lobster.sh

7. Copy the script to path

cp lobster.sh /usr/bin/lobster

8. Use lobster

lobster <args> or lobster [movie/tv show]

</details>

Usage

Usage: lobster [options] [query]
If a query is provided, it will be used to search for a Movie/TV Show

Options:
    -c, --continue
      Continue watching from current history
    -d, --download [path]
      Downloads movie or episode that is selected (if no path is provided, it defaults to the current directory)
    --discord, --discord-presence, --rpc, --presence
      Enables discord rich presence (beta feature, but should work fine on Linux)
    -e, --edit
      Edit config file using an editor defined with lobster_editor in the config (\$EDITOR by default)
    -h, --help
      Show this help message and exit
    -i, --image-preview
      Shows image previews during media selection (requires chafa, you can optionally use ueberzugpp)
    -j, --json
      Outputs the json containing video links, subtitle links, referrers etc. to stdout
    -l, --language [language]
      Specify the subtitle language (if no language is provided, it defaults to english)
    --rofi, --external-menu
      Use rofi instead of fzf
    -p, --provider
      Specify the provider to watch from (if no provider is provided, it defaults to Vidcloud) (currently supported: Vidcloud, UpCloud)
    -q, --quality
      Specify the video quality (if no quality is provided, it defaults to 1080)
    -r, --recent [movies|tv]
      Lets you select from the most recent movies or tv shows (if no argument is provided, it defaults to movies)
    -s, --syncplay
      Use Syncplay to watch with friends
    -t, --trending
      Lets you select from the most popular movies and shows
    -u, -U, --update
      Update the script
    -v, -V, --version
      Show the version of the script
    -x, --debug
      Enable debug mode (prints out debug info to stdout and also saves it to /tmp/lobster.log)

  Note:
    All arguments can be specified in the config file as well.
    If an argument is specified in both the config file and the command line, the command line argument will be used.

  Some example usages:
    lobster -i a silent voice --rofi
    lobster -l spanish -q 720 fight club -i -d
    lobster -l spanish blade runner --json

-c / --continue argument

This feature is disabled by default because it relies on history, to enable it, you need add the following line to the lobster_config.sh file:

history=true

In a similar fashion to how saving your position when you watch videos on YouTube or Netflix works, lobster has history support and saves the last minute you watched for a Movie or TV Show episode. To use this feature, simply watch a Movie or an Episode from a TV Show, and after you quit mpv the history will be automatically updated. The next time you want to resume from the last position watched, you can just run

lobster -c

which will prompt you to chose which of the saved Movies/TV Shows you'd like to resume from. Upon the completion of a movie or an episode, the corresponding entry is either deleted (in case of a movie, or the last episode of a show), or it is updated to the next available episode (if it's the last episode of a season, it will update to the first episode of the next season).

<details> <summary>Showcase</summary>

</details>

Please note:

• The history file can be found at ~/.local/share/lobster/lobster_history.txt
• A movie or TV show episode is automatically marked as completed/updated after the user watches more than 90% of its content

--clear-history / --delete-history argument

This argument allows you to delete the history file

-d / --download