{"id":17382988,"url":"https://github.com/justchokingaround/lobster","last_synced_at":"2025-05-15T09:08:17.743Z","repository":{"id":47346204,"uuid":"516058963","full_name":"justchokingaround/lobster","owner":"justchokingaround","description":"mmm lobster","archived":false,"fork":false,"pushed_at":"2025-05-08T21:55:18.000Z","size":191,"stargazers_count":657,"open_issues_count":17,"forks_count":41,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-05-08T22:34:31.023Z","etag":null,"topics":["free","linux","macos","movie","movies","mpv","scraper","series","shell","shell-script","shellscript","tv","tvshow","tvshows","ueberzugpp","windows"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justchokingaround.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-07-20T16:36:52.000Z","updated_at":"2025-05-08T21:55:22.000Z","dependencies_parsed_at":"2023-02-16T11:16:19.234Z","dependency_job_id":"8c57cac0-4b8b-46f5-93c9-aa5549c7fdd2","html_url":"https://github.com/justchokingaround/lobster","commit_stats":{"total_commits":205,"total_committers":18,"mean_commits":11.38888888888889,"dds":"0.12195121951219512","last_synced_commit":"3ae7fd8e2f9ddf6ee1b1df8098bcd1aa7afecab9"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justchokingaround%2Flobster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justchokingaround%2Flobster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justchokingaround%2Flobster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justchokingaround%2Flobster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justchokingaround","download_url":"https://codeload.github.com/justchokingaround/lobster/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310520,"owners_count":22049470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["free","linux","macos","movie","movies","mpv","scraper","series","shell","shell-script","shellscript","tv","tvshow","tvshows","ueberzugpp","windows"],"created_at":"2024-10-16T07:40:05.512Z","updated_at":"2025-05-15T09:08:12.732Z","avatar_url":"https://github.com/justchokingaround.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"### Showcase\n\nhttps://github.com/justchokingaround/lobster/assets/44473782/d597335c-42a9-4e45-8948-122744aa5ca9\n\n## Join the discord server (it is bridged to the matrix space)\n\n### https://discord.gg/JTDS2CKjQU\n\n## Join the matrix server (I am more active there)\n\n### https://matrix.to/#/#lobster-and-jerry:matrix.org\n\n## Overview\n\n- [Install](#install)\n  - [Arch linux](#arch)\n  - [Debian linux](#debian-using-makedeb-and-mist)\n  - [Linux](#linux-from-source)\n  - [Android](#android-requires-termux-and-mpv-android)\n  - [NixOS](#nixos-flake)\n  - [Mac](#mac)\n  - [Windows](#windows)\n- [Usage](#usage)\n  - [`-c` / `--continue`](#-c----continue-argument)\n  - [`--clear-history / --delete-history`](#--clear-history----delete-history-argument)\n  - [`-d` / `--download`](#-d----download-path-argument)\n  - [`--discord` / `--discord-presence` / `--rpc` / `--presence`](#--discord----discord-presence----rpc----presence-argument)\n  - [`-e` / `--edit`](#-e----edit-argument)\n  - [`-i` / `--image-preview`](#-i----image-preview-argument)\n  - [`-j` / `--json`](#-j----json-argument)\n  - [`-l` / `--language`](#-l----language-language-argument)\n  - [`--rofi` / `--external-menu`](#--rofi----external-menu-argument)\n  - [`-p` / `--provider`](#-p----provider-provider-argument)\n  - [`-q` / `--quality`](#-q----quality-quality-argument)\n  - [`--quiet`](#--quiet-argument)\n  - [`-r` / `--recent`](#r----recent-tvmovie-argument)\n  - [`-s` / `--syncplay`](#-s----syncplay-argument)\n  - [`-t` / `--trending`](#-t----trending-argument)\n  - [`-u` / `-U` / `--update`](#u---u----update-argument)\n  - [`-v` / `-V` / `--version`](#v---v----version-argument)\n  - [`-x` / `--debug`](#-x----debug-argument)\n- [Configuration](#configuration)\n- [Contributing](#contributing)\n- [Uninstall](#uninstall)\n\n## Install\n\n#### Arch\n\nNote: it is recommended to use the `lobster-git` package, as it is more up to\ndate, and as the project is currently being actively maintained\n\n```sh\nparu -S lobster-git\n```\n\nor\n\n```sh\nparu -S lobster\n```\n\n#### Debian (using makedeb and mist)\n\nHere are the full installation instructions for Debian:\n\nInstall the dependencies:\n\n```sh\nsudo apt update \u0026\u0026 sudo apt upgrade \u0026\u0026 sudo apt install git wget\n```\n\nDuring this step write `makedeb` and enter, when prompted:\n\n```sh\nbash -ci \"$(wget -qO - 'https://shlink.makedeb.org/install')\"\n```\n\n```sh\nwget -qO - 'https://proget.makedeb.org/debian-feeds/prebuilt-mpr.pub' | gpg --dearmor | sudo tee /usr/share/keyrings/prebuilt-mpr-archive-keyring.gpg 1\u003e /dev/null\n```\n\n```\necho \"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\n```\n\n```\nsudo apt update \u0026\u0026 sudo apt install mist\n```\n\nDuring this step when prompted to `Review files for 'lobster-git'? [Y/n]`, write\n`n` and enter.\n\n```sh\nmist update \u0026\u0026 mist install lobster-git\n```\n\n#### Linux (from source)\n\n```sh\nsudo curl -sL github.com/justchokingaround/lobster/raw/main/lobster.sh -o /usr/local/bin/lobster \u0026\u0026\nsudo chmod +x /usr/local/bin/lobster\n```\n\n#### Android (requires Termux and [mpv-android](https://github.com/mpv-android/mpv-android))\n\n```sh\ncurl -sLO github.com/justchokingaround/lobster/raw/main/lobster.sh \u0026\u0026\nchmod +x lobster.sh \u0026\u0026\nmv lobster.sh /data/data/com.termux/files/usr/bin/lobster\n```\n\nIf you're using Android 14 or newer make sure to run this before:\n```sh\npkg install termux-am\n```\n\n#### Nixos (Flake)\n\nAdd this to you flake.nix\n\n```nix\ninputs.lobster.url = \"github:justchokingaround/lobster\";\n```\n\nAdd this to you configuration.nix\n\n```nix\nenvironment.systemPackages = [\n  inputs.lobster.packages.\u003carchitecture\u003e.lobster\n];\n```\n\n##### Or for run the script once use\n\n```sh\nnix run github:justchokingaround/lobster#lobster\n```\n\n##### Nixos (Flake) update\n\nWhen encoutering errors first run the nix flake update command in the cloned\nproject and second add new/missing [dependencies](#dependencies) to the\ndefault.nix file. Use the\n[nixos package search](https://search.nixos.org/packages) to find the correct\nname.\n\n```nix\nnix flake update\n```\n\n#### Mac\n\n```sh\ncurl -sL github.com/justchokingaround/lobster/raw/main/lobster.sh -o \"$(brew --prefix)\"/bin/lobster \u0026\u0026\nchmod +x \"$(brew --prefix)\"/bin/lobster\n```\n\n#### Windows\n\n\u003cdetails\u003e\n\u003csummary\u003eWindows installation instructions\u003c/summary\u003e\n\n- This guide covers how to install and use lobster with the windows terminal,\n  you could also use a different terminal emulator, that supports fzf, like for\n  example wezterm\n- Note that the git bash terminal does _not_ have proper fzf support\n\n1. Install scoop\n\nOpen a PowerShell terminal\nhttps://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.2#msi\n(version 5.1 or later) and run:\n\n```ps\nSet-ExecutionPolicy RemoteSigned -Scope CurrentUser\nirm get.scoop.sh | iex\n```\n\n2. Install git,mpv and fzf\n\n```ps\nscoop bucket add extras\nscoop install git mpv fzf\n```\n\n3. Install windows terminal (you don't need to have a microsoft account for\n   that) https://learn.microsoft.com/en-us/windows/terminal/install\n\n4. Install git bash (select the option to add it to the windows terminal during\n   installation) https://git-scm.com/download/win\n\n(The next steps are to be done in the windows terminal, in a bash shell)\n\n5. Download the script file to the current directory\n\n```sh\ncurl -O \"https://raw.githubusercontent.com/justchokingaround/lobster/main/lobster.sh\"\n```\n\n6. Give it executable permissions\n\n```sh\nchmod +x lobster.sh\n```\n\n7. Copy the script to path\n\n```sh\ncp lobster.sh /usr/bin/lobster\n```\n\n8. Use lobster\n\n```sh\nlobster \u003cargs\u003e or lobster [movie/tv show]\n```\n\n\u003c/details\u003e\n\n## Usage\n\n```txt\nUsage: lobster [options] [query]\nIf a query is provided, it will be used to search for a Movie/TV Show\n\nOptions:\n    -c, --continue\n      Continue watching from current history\n    -d, --download [path]\n      Downloads movie or episode that is selected (if no path is provided, it defaults to the current directory)\n    --discord, --discord-presence, --rpc, --presence\n      Enables discord rich presence (beta feature, but should work fine on Linux)\n    -e, --edit\n      Edit config file using an editor defined with lobster_editor in the config (\\$EDITOR by default)\n    -h, --help\n      Show this help message and exit\n    -i, --image-preview\n      Shows image previews during media selection (requires chafa, you can optionally use ueberzugpp)\n    -j, --json\n      Outputs the json containing video links, subtitle links, referrers etc. to stdout\n    -l, --language [language]\n      Specify the subtitle language (if no language is provided, it defaults to english)\n    --rofi, --external-menu\n      Use rofi instead of fzf\n    -p, --provider\n      Specify the provider to watch from (if no provider is provided, it defaults to Vidcloud) (currently supported: Vidcloud, UpCloud)\n    -q, --quality\n      Specify the video quality (if no quality is provided, it defaults to 1080)\n    -r, --recent [movies|tv]\n      Lets you select from the most recent movies or tv shows (if no argument is provided, it defaults to movies)\n    -s, --syncplay\n      Use Syncplay to watch with friends\n    -t, --trending\n      Lets you select from the most popular movies and shows\n    -u, -U, --update\n      Update the script\n    -v, -V, --version\n      Show the version of the script\n    -x, --debug\n      Enable debug mode (prints out debug info to stdout and also saves it to /tmp/lobster.log)\n\n  Note:\n    All arguments can be specified in the config file as well.\n    If an argument is specified in both the config file and the command line, the command line argument will be used.\n\n  Some example usages:\n    lobster -i a silent voice --rofi\n    lobster -l spanish -q 720 fight club -i -d\n    lobster -l spanish blade runner --json\n```\n\n### `-c` / `--continue` argument\n\nThis feature is disabled by default because it relies on history, to enable it,\nyou need add the following line to the `lobster_config.sh` file:\n\n```sh\nhistory=true\n```\n\nIn a similar fashion to how saving your position when you watch videos on\nYouTube or Netflix works, lobster has history support and saves the last minute\nyou watched for a Movie or TV Show episode. To use this feature, simply watch a\nMovie or an Episode from a TV Show, and after you quit mpv the history will be\nautomatically updated. The next time you want to resume from the last position\nwatched, you can just run\n\n```sh\nlobster -c\n```\n\nwhich will prompt you to chose which of the saved Movies/TV Shows you'd like to\nresume from. Upon the completion of a movie or an episode, the corresponding\nentry is either deleted (in case of a movie, or the last episode of a show), or\nit is updated to the next available episode (if it's the last episode of a\nseason, it will update to the first episode of the next season).\n\n\u003cdetails\u003e\n\u003csummary\u003eShowcase\u003c/summary\u003e\n\n![image](https://github.com/justchokingaround/lobster/assets/44473782/5ed98fb9-008d-4068-a854-577245cfe1ee)\n\n![image](https://github.com/justchokingaround/lobster/assets/44473782/cd59329e-a1c8-408a-be48-690db2d52642)\n\n![image](https://github.com/justchokingaround/lobster/assets/44473782/fae5ea52-4dc4-41ee-b7a2-cbb2476f5819)\n\n\u003c/details\u003e\n\n#### Please note:\n\n- The history file can be found at `~/.local/share/lobster/lobster_history.txt`\n- A movie or TV show episode is automatically marked as completed/updated after\n  the user watches more than 90% of its content\n\n### --`clear-history` / `--delete-history` argument\n\nThis argument allows you to delete the history file\n\n### `-d` / `--download` `\u003cpath\u003e` argument\n\nThis option lets you use lobster as you normally would, with the exception that\ninstead of playing the video in your player of choice, it will instead download\nthe video. If no path is specified when passing this argument, then it will\ndownload to the current working directory, as an example, it would look like\nthis:\n\n```sh\nlobster -d '.' rick and morty\n```\n\nor\n\n```sh\nlobster rick and morty -d\n```\n\nIf you want to specify a path to which you would like to download the video, you\ncan do so by passing an additional parameter to the `-d` or `--download`\nargument, for instance: using a full path:\n\n```sh\nlobster -d \"/home/chomsky/tv_shows/rick_and_morty/\" rick and morty\n```\n\nor using a relative path:\n\n```sh\nlobster -d \"../rick_and_morty/\" rick and morty\n```\n\n### `--discord` / `--discord-presence` / `--rpc` / `--presence` argument\n\n#### Note: beta feature\n\nBy passing this argument you make use of discord rich presence so you can let\nyour friends know what you are watching.\n\nThis argument requires BSD netcat to be installed.\n\nOn Arch Linux you can install it using either pacman or your aur helper of\nchoice with:\n\n```sh\nparu -S openbsd-netcat\n```\n\n### `-e` / `--edit` argument\n\nBy passing this argument you can edit the config file using an editor of your\nchoice. By default it will use the editor defined in the `lobster_config.sh`\nfile, but if you don't have one defined, it will use the `$EDITOR` environment\nvariable (if it's not set, it will default to `vim`).\n\n### `-i` / `--image-preview` argument\n\nBy passing this argument you can see image previews when selecting an entry.\n\nFor `rofi` it will work out of the box, if you have icons enabled in your\ndefault configuration.\n\nExample using my custom rofi configuration (to customize how your rofi image\npreview looks, please check the [configuration](#configuration) section)\n\n\u003cdetails\u003e\n\u003csummary\u003eShowcase\u003c/summary\u003e\n\n![image](https://github.com/justchokingaround/lobster/assets/44473782/a8850f00-9491-4f86-939d-2f63bcb36e96)\n\n\u003c/details\u003e\n\nFor `fzf` you will need to either install\n[chafa](https://github.com/hpjansson/chafa/) or\n[ueberzugpp](https://github.com/jstkdng/ueberzugpp/).\n\n\u003cdetails\u003e\n\u003csummary\u003eShowcase\u003c/summary\u003e\n\n![image](https://github.com/justchokingaround/lobster/assets/44473782/8d8057d8-4d85-4f0e-b6c0-3b7dd5dce557)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstallation instructions for chafa/ueberzugpp\u003c/summary\u003e\n\nOn Arch Linux you can install it using your aur helper of choice with:\n\n```sh\nparu -S chafa\n```\n\nor\n\n```sh\nparu -S ueberzugpp\n```\n\nOn Mac you can install it using homebrew with:\n\n```sh\ncurl -s -O \"https://raw.githubusercontent.com/jstkdng/ueberzugpp/master/homebrew/ueberzugpp.rb\"\nbrew install ./ueberzugpp\nrm ueberzugpp\n```\n\nIn other cases, you can build it from\n[source](https://github.com/jstkdng/ueberzugpp/#build-from-source).\n\nUsing ueberzugpp is disabled by default in favor of chafa, to enable it, you\nneed add the following line to the `lobster_config.sh` file:\n\n```sh\nuse_ueberzugpp=true\n```\n\n\u003c/details\u003e\n\n### `-j` / `--json` argument\n\nBy passing this argument, you can output the json for the currently selected\nmedia to stdout, with the decrypted video link.\n\n### `-l` / `--language` `\u003clanguage\u003e` argument\n\nBy passing this argument, you can specify your preferred language for the\nsubtitles of a video. If no parameter is specified, it will default to\n`english`.\n\nExample use case:\n\n```sh\nlobster seven -l spanish\n```\n\nThis is also valid, and will use english as the defined subtitles language:\n\n```sh\nlobster -l weathering with you\n```\n\n### `--rofi` / `--external-menu` argument\n\nBy passing this argument, you can use rofi instead of fzf to interact with the\nlobster script.\n\nThis is the recommended way to use lobster, and is a core philosophy of this\nscript. My use case is that I have a keybind in my WM configuration that calls\nlobster, that way I can watch Movies and TV Shows without ever even opening the\nterminal.\n\nHere is an example of that looks like (without image preview):\n\n\u003cdetails\u003e\n\u003csummary\u003eShowcase\u003c/summary\u003e\n\n![image](https://github.com/justchokingaround/lobster/assets/44473782/d1243c17-0ef1-44b3-99a8-f2c4a4ab5da9)\n\n\u003c/details\u003e\n\n### `-p` / `--provider` `\u003cprovider\u003e` argument\n\nBy passing this argument, you can specify a preferred provider. The script\ncurrently supports the following providers: `UpCloud`, `Vidcloud`. If you don't\npass any provider in the parameters, it will default to `UpCloud`.\n\nExample use case:\n\n```sh\nlobster -p Vidcloud shawshank redemption\n```\n\nThis is also valid, but will use `UpCloud` instead:\n\n```sh\nlobster -p shawshank redemption\n```\n\n### `-q` / `--quality` `\u003cquality\u003e` argument\n\nBy passing this argument, you can specify a preferred quality for the video (if\nthose are present in the source). If you don't pass any quality in the\nparameters, it will default to `1080`.\n\nExample use case:\n\n```sh\nlobster -q 720 the godfather\n```\n\nThis is also valid, but will use `1080` instead:\n\n```sh\nlobster the godfather -q\n```\n\n### `-r` / `--recent` `\u003ctv|movie\u003e` argument\n\nBy passing this argument, you can see watch most recently released movies and TV\nshows. You can specify if you want to see movies or TV shows by passing the `tv`\nor `movie` parameter. If you don't pass any parameter, it will default to\n`movie`.\n\nExample use case:\n\n```sh\nlobster -r tv\n```\n\nThis is also valid, but will use `movie` instead:\n\n```sh\nlobster -r\n```\n\n### `-s` / `--syncplay` argument\n\nBy passing this argument, you can use [syncplay](https://syncplay.pl/) to watch\nvideos with your friends. This will only work if you have syncplay installed and\nconfigured.\n\n### `-t` / `--trending` argument\n\nBy passing this argument, you can see the most trending movies and TV shows.\n\n### `-u` / `-U` / `--update` argument\n\nBy passing this argument, you can update the script to the latest version.\n\nNote: you will most likely need to run this with `sudo`\n\nExample use case:\n\n```sh\nsudo lobster -u\n```\n\n### `-v` / `-V` / `--version` argument\n\nBy passing this argument, you can see the current version of the script. This is\nuseful if you want to check if you have the latest version installed.\n\n### `-x` / `--debug` argument\n\nBy passing this argument, you can see the debug output of the script. This will\nredirect all the stderr output to stdout, printing it to the terminal, while\nalso saving it to a log file: `/tmp/lobter.log`\n\nNote: fzf prints the finder to stderr, so this will also be redirected to\nstdout, and by extension printed to the terminal and saved to the log file.\n\n## Configuration\n\nPlease refer to the\n[wiki](https://github.com/justchokingaround/lobster/wiki/Configuration) for\ninformation on how to configure the script using the config file.\n\n## Contributing\n\nAll contributions are welcome, and I will to review them as soon as possible. If\nyou want to contribute, please follow the following recommendations:\n\n- All help is appreciated, even if it's just a typo fix, or a small improvement\n- You do not need to be a programmer to contribute, you can also help by opening\n  issues, or by testing the script and reporting bugs\n- You do not need to be very experienced with shell scripting to contribute, I\n  will gladly help you with any questions you might have, and I will also review\n  your code\n- If you are unsure about something, please open an issue first, start a\n  discussion or message me personally\n- Please make sure that your code is POSIX compliant (no bashisms)\n- Please make sure that your code passes `shellcheck`\n- Please use `shfmt` to format your code\n- If you are adding a new feature, please make sure that it is configurable\n  (either through the config file and/or through command line arguments)\n- I recommend reading the philosophy section of the README, to get a better\n  understanding of the project (TODO)\n\nYou can find the current roadmap here, which contains TODOs and the current\nprogress of the project:\nhttps://github.com/users/justchokingaround/projects/2/views/1?query=is%3Aopen+sort%3Aupdated-desc\n\n## Dependencies\n\n- fzf\n- curl\n- grep\n- sed\n- patch\n- awk\n- mpv\n- html-xml-utils (for fixing html encoded characters) (optional)\n- rofi (external menu)\n- socat (for getting the player position from the mpv socket)\n- vlc (optional)\n- iina (optional)\n\n### In case you don't have fzf installed, you can install it like this:\n\n```sh\ngit clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf\n~/.fzf/install\n```\n\n## Uninstall\n\n### Arch Linux\n\n```sh\nparu -R lobster\n```\n\n### Linux\n\n```sh\nsudo rm $(which lobster)\n```\n\n### Mac\n\n```sh\nrm \"$(brew --prefix)\"/bin/lobster\n```\n\n### Windows\n\n```sh\nrm /usr/bin/lobster\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustchokingaround%2Flobster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustchokingaround%2Flobster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustchokingaround%2Flobster/lists"}