README.md

   1 # NimCoon
   2
   3 Play videos from YouTube and PeerTube from the
   4 command line using your preferred desktop media player.
   5
   6 NewPipe app for Android offers similar features.
   7
   8 This application is implemented in [Nim language](https://nim-lang.org) using
   9 only the standard library.
  10
  11 ![nimcoon screenshot with search term 'baby yoda'](screenshot.png)
  12
  13 ## Motivation
  14
  15 ### No similar existing tool
  16
  17 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.
  18
  19 ### Digital Minimalism
  20
  21 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.
  22
  23 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.
  24
  25 I have had better success with managing my YouTube consumption after shifting to this tool. Settings inspired by Pinafore's wellness settings.
  26
  27 ### Why no issues or merge requests?
  28
  29 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.
  30
  31 ## Features
  32
  33 - [x] Search for videos using keywords
  34 - [x] Stream videos and music from YouTube
  35 - [x] Play direct links from YouTube and PeerTube
  36 - [x] Stream video and music from magnet links and hyperlinks to torrent files
  37 - [x] Download music
  38 - [x] Download video
  39 - [x] Play YouTube playlists (MPV only)
  40 - [ ] Download YouTube playlists
  41 - [x] Stream video from torrent file URLs
  42 - [x] BitTorrent is preferred for PeerTube video links
  43 - [ ] Search PeerTube (3.0 or later)
  44 - [ ] YouTube Autoplay (music only)
  45 - [ ] Configuration options
  46
  47 |                         | YouTube  | PeerTube (HTTP) | PeerTube (WebTorrent) |
  48 | --------                | -------- | --------        | --------              |
  49 | Music Streaming         | ✅       | ✅              | ✅                    |
  50 | Video Streaming         | ✅       | ✅              | ✅                    |
  51 | Music Download          | ✅       | ✅              |                       |
  52 | Video Download          | ✅       | ✅              |                       |
  53 | Stream Music from URL   | ✅       | ✅              |                       |
  54 | Stream Video from URL   | ✅       | ✅              | ✅                    |
  55 | Download Music from URL | ✅       | ✅              |                       |
  56 | Download Video from URL | ✅       | ✅              |                       |
  57 | Stream Music Playlist   | ✅       |                 |                       |
  58 | Stream Video Playlist   | ✅       |                 |                       |
  59 | Download Music Playlist |          |                 |                       |
  60 | Download Video Playlist |          |                 |                       |
  61
  62 ## Installation
  63
  64 Nim Coon depends on the following:
  65 - youtube-dl
  66 - mpv (recommended) or vlc
  67 - peerflix and webtorrent (for magnet links)
  68
  69 Install MPV or VLC using your distribution's package manager.
  70
  71 Install YouTube-dl
  72 ``` sh
  73 pip3 install --user youtube-dl
  74 ```
  75
  76 Install PeerFlix and WebTorrent
  77 ```sh
  78 npm install --global peerflix webtorrent-cli
  79 ```
  80
  81 (Optional) If you want your YouTube downloads to be faster, install `aria2` download manager.
  82
  83 ### Installing using Nimble
  84
  85 NimCoon can be installed from Nimble repositories:
  86
  87 ``` sh
  88 nimble install nimcoon
  89 ```
  90
  91 You can also install from source by running the following command:
  92
  93 ```sh
  94 nimble install
  95 ```
  96
  97 ### Installing binary
  98
  99 Download the latest build from GitlabCI (amd64 GNU/Linux only).
 100
 101 ```sh
 102 wget https://gitlab.com/njoseph/nimcoon/-/jobs/artifacts/master/download?job=compile -O artifacts.zip
 103 unzip artifacts.zip
 104 ```
 105
 106 Copy the binary to somewhere on your path like /usr/local/bin
 107
 108 ## Usage
 109
 110 ```sh
 111 nimcoon "emacs"
 112
 113 # If your search query has multiple words, use quotes
 114 nimcoon "nim lang"
 115
 116 # Play audio of the first search result
 117 nimcoon -m -l "counting stars"
 118
 119 # Download audio of the first search result
 120 nimcoon -mld "counting stars"
 121
 122 # Play direct video link
 123 nimcoon https://www.youtube.com/watch?v=QOEMv0S8AcA
 124
 125 # Add -d to download or -m to select only audio or both
 126 nimcoon -md https://www.youtube.com/watch?v=hT_nvWreIhg
 127 ```
 128
 129 After the search results are displayed, you can enter a number to play one
 130 result, "all" to play all the results or "q" to quit the program.
 131
 132 If a number is entered, after the selected search result is played, the results
 133 are redisplayed, so that you can play the other results without having to search
 134 again.
 135
 136 ### Command line arguments
 137
 138 | **Arguments**     | **Explanation**                            |
 139 |-------------------|--------------------------------------------|
 140 | -m, --music       | Play Music only, no video                  |
 141 | -l, --lucky       | Try your luck with the first search result |
 142 | -f, --full-screen | Play video in full screen                  |
 143 | -d, --download    | Download video or music                    |
 144
 145 Feel free to use these options in any combination. NimCoon will show a helpful
 146 error message if you pick incompatible options.
 147
 148 ## Development
 149
 150 One-liner for compiling and running
 151
 152 ```sh
 153 nim c -d:ssl -r src/nimcoon.nim 'nim lang'
 154 ```
 155
 156 ## Privacy
 157
 158 To avoid storing your nimcoon searches in `zsh` history, run this command
 159
 160 ```sh
 161 setopt histignorespace
 162 ```
 163
 164 Then, add a space before typing nimcoon in the shell, like " nimcoon"
 165
 166 ```sh
 167  nimcoon "this is private"
 168 ```
 169
 170 The same can be achieved in `bash` by setting an environment variable
 171 ```sh
 172 export HISTCONTROL=ignoreboth
 173 ```
 174