lobster_latest_demo.mp4
- Install
- 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
--quiet
-r
/--recent
-s
/--syncplay
-t
/--trending
-u
/-U
/--update
-v
/-V
/--version
-x
/--debug
- Configuration
- Contributing
- Uninstall
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
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
sudo curl -sL github.com/justchokingaround/lobster/raw/main/lobster.sh -o /usr/local/bin/lobster &&
sudo chmod +x /usr/local/bin/lobster
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
];
nix run github:justchokingaround/lobster#lobster
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
curl -sL github.com/justchokingaround/lobster/raw/main/lobster.sh -o "$(brew --prefix)"/bin/lobster &&
chmod +x "$(brew --prefix)"/bin/lobster
Windows installation instructions
- 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
- 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
- Install git,mpv and fzf
scoop bucket add extras
scoop install git mpv fzf
-
Install windows terminal (you don't need to have a microsoft account for that) https://learn.microsoft.com/en-us/windows/terminal/install
-
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)
- Download the script file to the current directory
curl -O "https://raw.githubusercontent.com/justchokingaround/lobster/main/lobster.sh"
- Give it executable permissions
chmod +x lobster.sh
- Copy the script to path
cp lobster.sh /usr/bin/lobster
- Use lobster
lobster <args> or lobster [movie/tv show]
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
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).
- 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
This argument allows you to delete the history file
This option lets you use lobster as you normally would, with the exception that instead of playing the video in your player of choice, it will instead download the video. If no path is specified when passing this argument, then it will download to the current working directory, as an example, it would look like this:
lobster -d '.' rick and morty
or
lobster rick and morty -d
If you want to specify a path to which you would like to download the video, you
can do so by passing an additional parameter to the -d
or --download
argument, for instance: using a full path:
lobster -d "/home/chomsky/tv_shows/rick_and_morty/" rick and morty
or using a relative path:
lobster -d "../rick_and_morty/" rick and morty
By passing this argument you make use of discord rich presence so you can let your friends know what you are watching.
This argument requires BSD netcat to be installed.
On Arch Linux you can install it using either pacman or your aur helper of choice with:
paru -S openbsd-netcat
By passing this argument you can edit the config file using an editor of your
choice. By default it will use the editor defined in the lobster_config.sh
file, but if you don't have one defined, it will use the $EDITOR
environment
variable (if it's not set, it will default to vim
).
By passing this argument you can see image previews when selecting an entry.
For rofi
it will work out of the box, if you have icons enabled in your
default configuration.
Example using my custom rofi configuration (to customize how your rofi image preview looks, please check the configuration section)
For fzf
you will need to either install
chafa or
ueberzugpp.
Installation instructions for chafa/ueberzugpp
On Arch Linux you can install it using your aur helper of choice with:
paru -S chafa
or
paru -S ueberzugpp
On Mac you can install it using homebrew with:
curl -s -O "https://raw.githubusercontent.com/jstkdng/ueberzugpp/master/homebrew/ueberzugpp.rb"
brew install ./ueberzugpp
rm ueberzugpp
In other cases, you can build it from source.
Using ueberzugpp is disabled by default in favor of chafa, to enable it, you
need add the following line to the lobster_config.sh
file:
use_ueberzugpp=true
By passing this argument, you can output the json for the currently selected media to stdout, with the decrypted video link.
By passing this argument, you can specify your preferred language for the
subtitles of a video. If no parameter is specified, it will default to
english
.
Example use case:
lobster seven -l spanish
This is also valid, and will use english as the defined subtitles language:
lobster -l weathering with you
By passing this argument, you can use rofi instead of fzf to interact with the lobster script.
This is the recommended way to use lobster, and is a core philosophy of this script. My use case is that I have a keybind in my WM configuration that calls lobster, that way I can watch Movies and TV Shows without ever even opening the terminal.
Here is an example of that looks like (without image preview):
By passing this argument, you can specify a preferred provider. The script
currently supports the following providers: UpCloud
, Vidcloud
. If you don't
pass any provider in the parameters, it will default to UpCloud
.
Example use case:
lobster -p Vidcloud shawshank redemption
This is also valid, but will use UpCloud
instead:
lobster -p shawshank redemption
By passing this argument, you can specify a preferred quality for the video (if
those are present in the source). If you don't pass any quality in the
parameters, it will default to 1080
.
Example use case:
lobster -q 720 the godfather
This is also valid, but will use 1080
instead:
lobster the godfather -q
By passing this argument, you can see watch most recently released movies and TV
shows. You can specify if you want to see movies or TV shows by passing the tv
or movie
parameter. If you don't pass any parameter, it will default to
movie
.
Example use case:
lobster -r tv
This is also valid, but will use movie
instead:
lobster -r
By passing this argument, you can use syncplay to watch videos with your friends. This will only work if you have syncplay installed and configured.
By passing this argument, you can see the most trending movies and TV shows.
By passing this argument, you can update the script to the latest version.
Note: you will most likely need to run this with sudo
Example use case:
sudo lobster -u
By passing this argument, you can see the current version of the script. This is useful if you want to check if you have the latest version installed.
By passing this argument, you can see the debug output of the script. This will
redirect all the stderr output to stdout, printing it to the terminal, while
also saving it to a log file: /tmp/lobter.log
Note: fzf prints the finder to stderr, so this will also be redirected to stdout, and by extension printed to the terminal and saved to the log file.
Please refer to the wiki for information on how to configure the script using the config file.
All contributions are welcome, and I will to review them as soon as possible. If you want to contribute, please follow the following recommendations:
- All help is appreciated, even if it's just a typo fix, or a small improvement
- You do not need to be a programmer to contribute, you can also help by opening issues, or by testing the script and reporting bugs
- You do not need to be very experienced with shell scripting to contribute, I will gladly help you with any questions you might have, and I will also review your code
- If you are unsure about something, please open an issue first, start a discussion or message me personally
- Please make sure that your code is POSIX compliant (no bashisms)
- Please make sure that your code passes
shellcheck
- Please use
shfmt
to format your code - If you are adding a new feature, please make sure that it is configurable (either through the config file and/or through command line arguments)
- I recommend reading the philosophy section of the README, to get a better understanding of the project (TODO)
You can find the current roadmap here, which contains TODOs and the current progress of the project: https://github.com/users/justchokingaround/projects/2/views/1?query=is%3Aopen+sort%3Aupdated-desc
- fzf
- curl
- grep
- sed
- patch
- awk
- mpv
- html-xml-utils (for fixing html encoded characters) (optional)
- rofi (external menu)
- socat (for getting the player position from the mpv socket)
- vlc (optional)
- iina (optional)
git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install
paru -R lobster
sudo rm $(which lobster)
rm "$(brew --prefix)"/bin/lobster
rm /usr/bin/lobster