README.md

   1 # Nimcoon
   2
   3 Play videos from YouTube and PeerTube from the command line using your preferred desktop media player.
   4
   5 Similar apps for other platforms:
   6
   7 - [NewPipe](https://newpipe.schabi.org) is a light-weight YouTube frontend for Android
   8 - [FreeTube](https://freetubeapp.io) is a GUI client for desktop platforms (uses electron)
   9
  10 This is a minimal application implemented in [Nim language](https://nim-lang.org) using only the standard library.
  11
  12 ![nimcoon screenshot with search term 'baby yoda'](screenshot.png)
  13
  14 ## Logo
  15
  16 A Maine Coon cat wearing a golden crown.
  17 Logo contributions/suggestions welcome.
  18
  19 Maybe I would've just called this project Maine Coon had I written it in Python, but I wanted to use this opportunity to make Nim popular.
  20
  21 ## Motivation
  22
  23 ### No similar existing tool
  24
  25 I tried all kinds of alternative YouTube players for the desktop. Most are either electron apps or slow web proxies. There was one cool bash script that did most of what I wanted called `ytview` but it had no way of copying the URL. I added this feature to the bash script but was still unsatisfied. There were CLI players written in Python but are usually a pain to install. They depend on a hard-coded YouTube API token and suffer from rate-limiting. I use youtube-dl with mpv usually (mostly because I like MPV over the YouTube JavaScript player). These tools have hundreds of options and I can't remember them. I needed a wrapper for them that does what I want, is easy to install(portable) and has a simple interface. I am not a big fan of Golang and its fat binaries. I discovered Nim around the same time I had this problem and decided to write this tool using just the standard library.
  26
  27 ### Digital Minimalism
  28
  29 YouTube's business incentive is to make you watch as many videos as possible. If you open the YouTube website and are logged into it, you will just get distracted by recommendations and forget why you opened it in the first place. You might have wanted to watch a conference talk but end up going down a rabbit hole of other "interesting" videos customized for you.
  30
  31 Nimcoon has a spartan design. It doesn't even show images of the search results. It doesn't let you browse YouTube. You have to explicitly search for something.
  32
  33 I have had better success with managing my YouTube consumption after shifting to this tool. Settings inspired by Pinafore's wellness settings.
  34
  35 ### Why no issues or merge requests?
  36
  37 I made this just for myself. The development is completely based on my needs and wants. I am not going to put a lot of work into this project. But feel free to use it if it works for you.
  38
  39 ## Features
  40
  41 - [x] Search for videos using keywords
  42 - [x] Stream videos and music from YouTube
  43 - [x] Play direct links from YouTube and PeerTube
  44 - [x] Stream video and music from magnet links and hyperlinks to torrent files
  45 - [x] Download music
  46 - [x] Download video
  47 - [x] Play YouTube playlists (MPV only)
  48 - [ ] Download YouTube playlists
  49 - [x] Stream video from torrent file URLs
  50 - [x] BitTorrent is preferred for PeerTube video links
  51 - [ ] Search PeerTube (3.0 or later)
  52 - [x] YouTube Autoplay (music only)
  53 - [ ] Configuration options
  54
  55 |                         | YouTube  | PeerTube (HTTP) | PeerTube (WebTorrent) |
  56 | --------                | -------- | --------        | --------              |
  57 | Music Streaming         | ✅       | ✅              | ✅                    |
  58 | Video Streaming         | ✅       | ✅              | ✅                    |
  59 | Music Download          | ✅       | ✅              |                       |
  60 | Video Download          | ✅       | ✅              |                       |
  61 | Stream Music from URL   | ✅       | ✅              |                       |
  62 | Stream Video from URL   | ✅       | ✅              | ✅                    |
  63 | Download Music from URL | ✅       | ✅              |                       |
  64 | Download Video from URL | ✅       | ✅              |                       |
  65 | Stream Music Playlist   | ✅       |                 |                       |
  66 | Stream Video Playlist   | ✅       |                 |                       |
  67 | Download Music Playlist |          |                 |                       |
  68 | Download Video Playlist |          |                 |                       |
  69 | Play Recommended Music  | ✅       |                 |                       |
  70
  71 ## Installation
  72
  73 Nim Coon depends on the following:
  74 - yt-dlp
  75 - mpv (recommended) or vlc
  76 - webtorrent (for magnet links)
  77
  78 Install MPV or VLC using your distribution's package manager.
  79
  80 Install yt-dlp
  81 ``` sh
  82 pip3 install --user yt-dlp
  83 ```
  84
  85 Install WebTorrent
  86 ```sh
  87 npm install --global webtorrent-cli
  88 ```
  89
  90 (Optional) If you want your YouTube downloads to be faster, install `aria2` download manager.
  91
  92 ### Installing using Nimble
  93
  94 Nimcoon can be installed from Nimble repositories:
  95
  96 ``` sh
  97 nimble install nimcoon
  98 ```
  99
 100 You can also install from source by running the following command:
 101
 102 ```sh
 103 nimble install
 104 ```
 105
 106 ### Installing binary
 107
 108 Download the latest build from GitlabCI (amd64 GNU/Linux only).
 109
 110 ```sh
 111 wget https://gitlab.com/njoseph/nimcoon/-/jobs/artifacts/master/download?job=compile -O artifacts.zip
 112 unzip artifacts.zip
 113 ```
 114
 115 Copy the binary to somewhere on your path like /usr/local/bin
 116
 117 ## Usage
 118
 119 ```sh
 120 nimcoon "emacs"
 121
 122 # If your search query has multiple words, use quotes
 123 nimcoon "nim lang"
 124
 125 # Play audio of the first search result
 126 nimcoon -m -l "counting stars"
 127
 128 # Download audio of the first search result
 129 nimcoon -mld "counting stars"
 130
 131 # Play direct video link
 132 nimcoon https://www.youtube.com/watch?v=QOEMv0S8AcA
 133
 134 # Add -d to download or -m to select only audio or both
 135 nimcoon -md https://www.youtube.com/watch?v=hT_nvWreIhg
 136 ```
 137
 138 After the search results are displayed, you can enter a number to play one
 139 result, "all" to play all the results or "q" to quit the program.
 140
 141 If a number is entered, after the selected search result is played, the results
 142 are redisplayed, so that you can play the other results without having to search
 143 again.
 144
 145 ### Command line arguments
 146
 147 Nimcoon provides both interactive and non-interactive arguments with significant
 148 overlap. But some arguments might only be present in one mode.
 149
 150 Non-interactive arguments are specified to the nimcoon program and apply
 151 globally to all search results in that session. These can be overriden on a
 152 case-by-case basis using the interactive arguments.
 153
 154 | **Non-interactive Arguments** | **Explanation**                            |
 155 |-------------------------------|--------------------------------------------|
 156 | -m, --music                   | Play Music only, no video                  |
 157 | -l, --lucky                   | Try your luck with the first search result |
 158 | -f, --full-screen             | Play video in full screen                  |
 159 | -d, --download                | Download video or music                    |
 160 | -a, --auto-play               | Play the next search result (YouTube only) |
 161
 162 Feel free to use these options in any combination. Nimcoon will show a helpful
 163 error message if you pick incompatible options.
 164
 165 Interactive arguments are provided during selection of a search result. These
 166 options allow you to change your mind after performing the search. For example,
 167 you might have searched for a music video, watched it and want to download the
 168 music only. In this case, you can specify the search result followed by the
 169 options as single characters. i.e
 170
 171 "1" plays the video
 172 "1 md" downloads the music of the video
 173
 174 | **Interactive Arguments** | **Explanation**                            |
 175 |---------------------------|--------------------------------------------|
 176 | -m, --music               | Play Music only, no video                  |
 177 | -f, --full-screen         | Play video in full screen                  |
 178 | -d, --download            | Download video or music                    |
 179 | -a, --auto-play           | Play the next search result (YouTube only) |
 180
 181 Auto-playing videos leads to binge watching. The default option in Nimcoon is to
 182 support auto-play for music only.
 183
 184 ## Development
 185
 186 One-liner for compiling and running
 187
 188 ```sh
 189 nim c -d:ssl -r src/nimcoon.nim 'nim lang'
 190 ```
 191
 192 ## Privacy
 193
 194 To avoid storing your nimcoon searches in `zsh` history, run this command
 195
 196 ```sh
 197 setopt histignorespace
 198 ```
 199
 200 Then, add a space before typing nimcoon in the shell, like " nimcoon"
 201
 202 ```sh
 203  nimcoon "this is private"
 204 ```
 205
 206 The same can be achieved in `bash` by setting an environment variable
 207 ```sh
 208 export HISTCONTROL=ignoreboth
 209 ```
 210