From 0cb50cd506e403ade3623e81ed01b2b3fbe43f10 Mon Sep 17 00:00:00 2001 From: Benedict Xavier <81157281+Benexl@users.noreply.github.com> Date: Fri, 20 Dec 2024 13:55:39 +0300 Subject: [PATCH 1/2] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index dd48435..1fdfd89 100644 --- a/README.md +++ b/README.md @@ -202,6 +202,8 @@ More pr's less issues 🙃 Show your support by starring the GitHub repository. +[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/Y8Y8ZAA7N) + ## Disclaimer > [!IMPORTANT] From 8023edcf3a109a02115e7bb2dd408191725a3456 Mon Sep 17 00:00:00 2001 From: Benedict Xavier <81157281+Benexl@users.noreply.github.com> Date: Mon, 23 Dec 2024 20:45:07 +0300 Subject: [PATCH 2/2] Update README.md --- README.md | 605 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 605 insertions(+) diff --git a/README.md b/README.md index 1fdfd89..aad8998 100644 --- a/README.md +++ b/README.md @@ -189,6 +189,611 @@ The only required external dependency, unless you won't be streaming, is [MPV](h - [ffmpegthumbnailer](https://github.com/dirkvdb/ffmpegthumbnailer) used for local previews of downloaded anime - [syncplay](https://syncplay.pl/) to enable watch together. - [feh](https://github.com/derf/feh) used in manga mode + + +## Usage + +The project offers a featureful command-line interface and MPV interface through the use of python-mpv. +The project also offers subs in different languages thanks to hianime provider. + +### The Commandline interface :fire: + +Designed for efficiency and automation. Plus has a beautiful pseudo-TUI in some of the commands. +If you are stuck anywhere just use `--help` before the command you would like to get help on + +**Overview of main commands:** + +- `fastanime anilist`: Powerful command for browsing and exploring anime due to AniList integration. +- `fastanime download`: Download anime. +- `fastanime search`: Powerful command meant for binging since it doesn't require the interfaces +- `fastanime downloads`: View downloaded anime and watch with MPV. +- `fastanime config`: Quickly edit configuration settings. +- `fastanime cache`: Quickly manage the cache fastanime uses +- `fastanime update`: Quickly update fastanime +- `fastanime grab`: print streams to stdout to use in non python application. + +**Overview of options** + +Most options are directly passed into fastanime directly and are shared by multiple subcommands. + +Most of the options override your config file. + +This is a convention to make the dev time faster since it reduces redundancy and also makes switching of subcommands with the same options easier to the end user. + +In general `fastanime --` + +Available options for the fastanime include: + +- `--server ` or `-s ` set the default server to auto select +- `--continue/--no-continue` or `-c/-no-c` whether to continue from the last episode you were watching +- `--local-history/--remote-history` whether to use remote or local history defaults to local +- `--quality <1080/720/480/360>` or `-q <1080/720/480/360>` the link to choose from server +- `--translation-type ` or `-t ` what language for anime +- `--dub` dubbed anime +- `--sub` subbed anime +- `--auto-select/--no-auto-select` or `-a/-no-a` auto select title from provider results +- `--auto-next/--no-auto-next` or `-A/-no-A` auto select next episode +- `-downloads-dir ` or `-d ` set the folder to download anime into +- `--fzf` use fzf for the ui +- `--default` use the default ui +- `--preview` show a preview when using fzf +- `--no-preview` dont show a preview when using fzf +- `--format ` or `-f ` set the format of anime downloaded and streamed based on [yt-dlp format](https://github.com/yt-dlp/yt-dlp#format-selection). Works when `--server gogoanime` or on providers that provide multi quality streams eg hianime +- `--icons/--no-icons` toggle the visibility of the icons +- `--skip/--no-skip` whether to skip the opening and ending theme songs. +- `--rofi` use rofi for the ui +- `--rofi-theme ` theme to use with rofi +- `--rofi-theme-input ` theme to use with rofi input +- `--rofi-theme-confirm ` theme to use with rofi confirm +- `--log` allow logging to stdout +- `--log-file` allow logging to a file +- `--rich-traceback` allow rich traceback +- `--use-mpv-mod/--use-default-player` whether to use python-mpv +- `--provider ` anime site of choice to scrape from +- `--sync-play` or `-sp` use syncplay for streaming anime so you can watch with your friends +- `--sub-lang ` regex is used to determine the appropriate. Only works when provider is hianime. +- `--normalize-titles/--no-normalize-titles` whether to normalize provider titles +- `--manga` toggle experimental manga mode + +Example usage of the above options + +```bash +# example of syncplay intergration +fastanime --sync-play --server sharepoint search -t + +# --- or --- + +# to watch with anilist intergration +fastanime --sync-play --server sharepoint anilist + +# downloading dubbed anime +fastanime --dub download -t + +# use icons and fzf for a more elegant ui with preview +fastanime --icons --preview --fzf anilist + +# use icons with default ui +fastanime --icons --default anilist + +# viewing manga +fastanime --manga search -t +``` + +#### The anilist command :fire: :fire: :fire: + +Uses the [AniList API](https://github.com/AniList/ApiV2-GraphQL-Docs) to create a terminal anilist client which is then intergrated with the scraping capabilities of the project. + +##### Running without any subcommand + +Run `fastanime anilist` to access the main interface. + +##### Subcommands + +The subcommands are mainly their as convenience. Since all the features already exist in the main interface. +Most of the subcommands share the common option `--dump-json` or `-d` which will print only the json data and suppress the ui. + +- `fastanime anilist trending`: Top 15 trending anime. +- `fastanime anilist recent`: Top 15 recently updated anime. +- `fastanime anilist search`: Search for anime (top 50 results). +- `fastanime anilist upcoming`: Top 15 upcoming anime. +- `fastanime anilist popular`: Top 15 popular anime. +- `fastanime anilist favourites`: Top 15 favorite anime. +- `fastanime anilist random`: get random anime + +**FastAnime Anilist Search subcommand** 🔥 🔥 🔥 + +It is by far one of the most powerful commands. +It offers the following options: + +- `--sort ` or `-s ` +- `--title ` or `-t ` +- `--tags ` or `-T ` can be specified multiple times for different tags to filter by. +- `--year ` or `-y ` +- `--status ` or `-S ` can be specified multiple times +- `--media-format ` or `-f ` +- `--season ` +- `--genres ` or `-g ` can be specified multiple times. +- `--on-list/--not-on-list` + +Example: + +```bash +# get anime with the tag of isekai +fastanime anilist search -T isekai + +# get anime of 2024 and sort by popularity +# that has already finished airing or is releasing +# and is not in your anime lists +fastanime anilist search -y 2024 -s POPULARITY_DESC --status RELEASING --status FINISHED --not-on-list + +# get anime of 2024 season WINTER +fastanime anilist search -y 2024 --season WINTER + +# get anime genre action and tag isekai,magic + fastanime anilist search -g Action -T Isekai -T Magic + +# get anime of 2024 thats finished airing +fastanime anilist search -y 2024 -S FINISHED + +# get the most favourite anime movies +fastanime anilist search -f MOVIE -s FAVOURITES_DESC +``` + +For more details visit the anilist docs or just get the completions which will improve the experience. + +Like seriously **[get the completions](https://github.com/FastAnime/FastAnime#completions-subcommand)** and the experience will be a 💯 💯 better. + +**Fastanime anilist download:** +Supports all the options for search except its used for downloading. +it also supports all options for `fastanime download` +Example: + +```bash +# get anime with the tag of isekai +fastanime anilist download -T isekai + +# get anime of 2024 and sort by popularity +# that has already finished airing or is releasing +# and is not in your anime lists +fastanime anilist download -y 2024 -s POPULARITY_DESC --status RELEASING --status FINISHED --not-on-list + +# get anime of 2024 season WINTER +fastanime anilist download -y 2024 --season WINTER + +# get anime genre action and tag isekai,magic + fastanime anilist download -g Action -T Isekai -T Magic + +# get anime of 2024 thats finished airing +fastanime anilist download -y 2024 -S FINISHED + +# get the most favourite anime movies +fastanime anilist download -f MOVIE -s FAVOURITES_DESC +``` + +The following are commands you can only run if you are signed in to your AniList account: + +- `fastanime anilist watching` +- `fastanime anilist planning` +- `fastanime anilist rewatching` +- `fastanime anilist dropped` +- `fastanime anilist paused` +- `fastanime anilist completed` + +Plus: `fastanime anilist notifier` 🔥 + +```bash +# basic form +fastanime anilist notifier + +# with logging to stdout +fastanime --log anilist notifier + +# with logging to a file. stored in the same place as your config +fastanime --log-file anilist notifier +``` + +The above commands will start a loop that checks every 2 minutes if any of the anime in your watch list that are airing has just released a new episode. + +The notification will consist of a cover image of the anime in none windows systems. + +You can place the command among your machines startup scripts. + +For fish users for example you can decide to put this in your `~/.config/fish/config.fish`: + +```fish +if ! ps aux | grep -q '[f]astanime .* notifier' + echo initializing fastanime anilist notifier + nohup fastanime --log-file anilist notifier>/dev/null & +end +``` + +> [!NOTE] +> To sign in just run `fastanime anilist login` and follow the instructions. +> To view your login status `fastanime anilist login --status` +> To erase login data `fastanime anilist login --erase` + +#### download subcommand + +Download anime to watch later dub or sub with this one command. +Its optimized for scripting due to fuzzy matching; basically you don't have to manually select search results. + +So every step of the way has been and can be automated. +Uses a list slicing syntax similar to that of python as the value for the `-r` option. + +> [!NOTE] +> +> The download feature is powered by [yt-dlp](https://github.com/yt-dlp/yt-dlp) so all the bells and whistles that it provides are readily available in the project. +> Like continuing from where you left of while downloading, after lets say you lost your internet connection. + +**Syntax:** + +```bash +# Download all available episodes +# multiple titles can be specified with -t option +fastanime download -t -t +# -- or -- +fastanime download -t -t -r ':' + +# download latest episode for the two anime titles +# the number can be any no of latest episodes but a minus sign +# must be present +fastanime download -t -t -r '-1' + +# latest 5 +fastanime download -t -t -r '-5' + +# Download specific episode range +# be sure to observe the range Syntax +fastanime download -t -r '::' + +fastanime download -t -r ':' + +fastanime download -t -r ':' + +fastanime download -t -r ':' + +# download specific episode +# remember python indexing starts at 0 +fastanime download -t -r ':' + +# merge subtitles with ffmpeg to mkv format; hianime tends to give subs as separate files +# and dont prompt for anything +# eg existing file in destination instead remove +# and clean +# ie remove original files (sub file and vid file) +# only keep merged files +fastanime download -t --merge --clean --no-prompt + +# EOF is used since -t always expects a title +# you can supply anime titles from file or -t at the same time +# +# from stdin +echo -e "\n\n" | fastanime download -t "EOF" -r -f - + +# from file +fastanime download -t "EOF" -r -f + + +``` + +#### search subcommand + +Powerful command mainly aimed at binging anime. Since it doesn't require interaction with the interfaces. + +Uses a list slicing syntax similar to that of python as the value of the `-r` option. + +**Syntax:** + +```bash +# basic form where you will still be prompted for the episode number +# multiple titles can be specified with the -t option +fastanime search -t -t + +# binge all episodes with this command +fastanime search -t -r ':' + +# watch latest episode +fastanime search -t -r '-1' + +# binge a specific episode range with this command +# be sure to observe the range Syntax +fastanime search -t -r ':' + +fastanime search -t -r '::' + +fastanime search -t -r ':' + +fastanime search -t -r ':' +``` + +#### grab subcommand + +Helper command to print streams to stdout so it can be used by non-python applications. + +The format of the printed out data is json and can be either an array or object depending on how many anime titles have been specified in the command-line or through a subprocess. + +> [!TIP] +> For python applications just use its python api, for even greater and easier control. +> So just add fastanime as one of your dependencies. + +Uses a list slicing syntax similar to that of python as the value of the `-r` option. + +**Syntax:** + +```bash +# --- print anime info + episode streams --- + +# multiple titles can be specified with the -t option +fastanime grab -t -t + +# -- or -- + +# print all available episodes +fastanime grab -t -r ':' + +# print the latest episode +fastanime grab -t -r '-1' + +# print a specific episode range +# be sure to observe the range Syntax +fastanime grab -t -r ':' + +fastanime grab -t -r '::' + +fastanime grab -t -r ':' + +fastanime grab -t -r ':' + +# --- grab options --- + +# print search results only +fastanime grab -t -r --search-results-only + +# print anime info only +fastanime grab -t -r --anime-info-only + +# print episode streams only +fastanime grab -t -r --episode-streams-only + +``` + +#### downloads subcommand + +View and stream the anime you downloaded using MPV. + +**Syntax:** + +```bash +fastanime downloads + +# view individual episodes +fastanime downloads --view-episodes +# --- or --- +fastanime downloads -v + +# to set seek time when using ffmpegthumbnailer for local previews +# -1 means random and is the default +fastanime downloads --time-to-seek +# --- or --- +fastanime downloads -t + +# to watch a specific title +# be sure to get the completions for the best experience +fastanime downloads --title + +# to get the path to the downloads folder set +fastanime downloads --path +# useful when you want to use the value for other programs + +``` + +#### config subcommand + +Edit FastAnime configuration settings using your preferred editor (based on `$EDITOR` environment variable so be sure to set it). + +**Syntax:** + +```bash +fastanime config + +# to get config path which is useful if you want to use it for another program. +fastanime config --path + +# add a desktop entry +fastanime config --desktop-entry + +# view current contents of your configuration or can be used to get an example config +fastanime config --view +``` + +> [!Note] +> +> If it opens [vim](https://www.vim.org/download.php) you can exit by typing `:q` 😉. + +#### cache subcommand + +Easily manage the data fastanime has cached; for the previews. + +**Syntax:** + +```bash +# delete everything in the cache dir +fastanime cache --clean + +# print the path to the cache dir and exit +fastanime cache --path + +# print the current size of the cache dir and exit +fastanime cache --size + +# open the cache dir and exit +fastanime cache +``` + +#### update subcommand + +Easily update fastanime to latest + +**Syntax:** + +```bash +# update fastanime to latest +fastanime update + +# check for latest release +fastanime update --check +``` + +#### completions subcommand + +Helper command to setup shell completions + +**Syntax:** + +```bash +# try to detect your shell and print completions +fastanime completions +# print fish completions +fastanime completions --fish +# print bash completions +fastanime completions --bash +# print zsh completions +fastanime completions --zsh +``` + +#### fastanime serve + +Helper command that starts a rest server. +This requires you to install fastanime with the api extra or standard extra. + +```bash +# default options +fastanime serve + +# specify host and port +fastanime serve --host <host> --port <port> +``` + +### MPV specific commands + +The project now allows on the fly media controls directly from mpv. This means you can go to the next or previous episode without the window ever closing thus offering a seamless experience. +This is all powered with [python-mpv]() which enables writing mpv scripts with python just like how it would be done in lua. + +#### Key Bindings + +`<shift>+n` fetch the next episode + +`<shift>+p` fetch the previous episode + +`<shift>+t` toggle the translation type from dub to sub + +`<shift>+a` toggle auto next episode + +`<shit>+r` reload episode + +#### Script Messages + +Commands issued in the MPV console. + +Examples: + +```bash +# to select episode from mpv without window closing +script-message select-episode <episode-number> + +# to select server from mpv without window closing +script-message select-server <server-name> + +# to select quality +script-message select-quality <1080/720/480/360> +``` + +## styling the default interface + +The default interface uses inquirerPy which is customizable. Read here to findout more <https://inquirerpy.readthedocs.io/en/latest/pages/env.html> + +## Configuration + +The app includes sensible defaults but can be customized extensively. Configuration is stored in `.ini` format at `~/.config/FastAnime/config.ini` on arch linux; for the other operating systems you can check by running `fastanime config --path`. + +> [!TIP] +> You can now use the option `--update` to update your config file from the command-line +> For Example: +> `fastanime --icons --fzf --preview config --update` +> the above will set icons to true, use_fzf to true and preview to true in your config file + +By default if a config file does not exist it will be auto created with comments to explain each and every option. +The default config: + +```ini +[general] +icons = False + +quality = 1080 + +normalize_titles = True + +provider = allanime + +preferred_language = english + +downloads_dir = ~/Videos/FastAnime + +preview = False + +ffmpegthumbnailer_seek_time = -1 + +use_fzf = False + +use_rofi = False + +rofi_theme = + +rofi_theme_input = + +rofi_theme_confirm = + +notification_duration = 2 + +sub_lang = eng + +default_media_list_tracking = None + +force_forward_tracking = True + +cache_requests = True + +use_persistent_provider_store = False + +recent = 50 + + +[stream] +continue_from_history = True + +preferred_history = local + +translation_type = sub + +server = top + +auto_next = False + +auto_select = True + +skip = False + +episode_complete_at = 80 + +use_python_mpv = False + +force_window = immediate + +format = best[height<=1080]/bestvideo[height<=1080]+bestaudio/best + +player = mpv +``` + ## Contributing