]>
Commit | Line | Data |
---|---|---|
81fb030b | 1 | # Nimcoon |
726cf1a7 | 2 | |
cc78bba9 | 3 | Play videos from YouTube and PeerTube from the command line using your preferred desktop media player. |
44978125 | 4 | |
cc78bba9 | 5 | Similar apps for other platforms: |
893b4f6c | 6 | |
cc78bba9 JN |
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. | |
a6c167a7 | 11 | |
3c20e75c | 12 | ![nimcoon screenshot with search term 'baby yoda'](screenshot.png) |
44978125 | 13 | |
cc78bba9 JN |
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 | ||
ca251617 JN |
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 | ||
81fb030b | 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. |
26229fac JN |
32 | |
33 | I have had better success with managing my YouTube consumption after shifting to this tool. Settings inspired by Pinafore's wellness settings. | |
ca251617 JN |
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 | ||
44978125 JN |
39 | ## Features |
40 | ||
41 | - [x] Search for videos using keywords | |
763f653f | 42 | - [x] Stream videos and music from YouTube |
52ecc638 | 43 | - [x] Play direct links from YouTube and PeerTube |
d7688e97 | 44 | - [x] Stream video and music from magnet links and hyperlinks to torrent files |
e9f0c7d0 | 45 | - [x] Download music |
d2ebe4d2 | 46 | - [x] Download video |
893b4f6c JN |
47 | - [x] Play YouTube playlists (MPV only) |
48 | - [ ] Download YouTube playlists | |
c12cc641 JN |
49 | - [x] Stream video from torrent file URLs |
50 | - [x] BitTorrent is preferred for PeerTube video links | |
51 | - [ ] Search PeerTube (3.0 or later) | |
5f9cdfef | 52 | - [x] YouTube Autoplay (music only) |
44978125 JN |
53 | - [ ] Configuration options |
54 | ||
dfe4f811 JN |
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 | | | | | |
5f9cdfef | 69 | | Play Recommended Music | ✅ | | | |
893b4f6c | 70 | |
3f6de5cb | 71 | ## Installation |
44978125 | 72 | |
3c20e75c | 73 | Nim Coon depends on the following: |
f4db2dfe | 74 | - yt-dlp |
7d08d1af | 75 | - mpv (recommended) or vlc |
f114ff9a | 76 | - webtorrent (for magnet links) |
7d08d1af | 77 | |
8d06ad69 | 78 | Install MPV or VLC using your distribution's package manager. |
88a5646a | 79 | |
f4db2dfe | 80 | Install yt-dlp |
88a5646a | 81 | ``` sh |
f4db2dfe | 82 | pip3 install --user yt-dlp |
88a5646a JN |
83 | ``` |
84 | ||
f114ff9a | 85 | Install WebTorrent |
88a5646a | 86 | ```sh |
f114ff9a | 87 | npm install --global webtorrent-cli |
88a5646a JN |
88 | ``` |
89 | ||
0c2f0385 JN |
90 | (Optional) If you want your YouTube downloads to be faster, install `aria2` download manager. |
91 | ||
af9a966f JN |
92 | ### Installing using Nimble |
93 | ||
81fb030b | 94 | Nimcoon can be installed from Nimble repositories: |
af9a966f JN |
95 | |
96 | ``` sh | |
97 | nimble install nimcoon | |
98 | ``` | |
99 | ||
100 | You can also install from source by running the following command: | |
44978125 | 101 | |
c4aeb618 | 102 | ```sh |
af9a966f | 103 | nimble install |
c4aeb618 JN |
104 | ``` |
105 | ||
af9a966f | 106 | ### Installing binary |
44978125 | 107 | |
af9a966f | 108 | Download the latest build from GitlabCI (amd64 GNU/Linux only). |
44978125 | 109 | |
3f6de5cb | 110 | ```sh |
af9a966f JN |
111 | wget https://gitlab.com/njoseph/nimcoon/-/jobs/artifacts/master/download?job=compile -O artifacts.zip |
112 | unzip artifacts.zip | |
44978125 JN |
113 | ``` |
114 | ||
af9a966f JN |
115 | Copy the binary to somewhere on your path like /usr/local/bin |
116 | ||
3f6de5cb | 117 | ## Usage |
44978125 JN |
118 | |
119 | ```sh | |
763f653f | 120 | nimcoon "emacs" |
44978125 | 121 | |
c4aeb618 | 122 | # If your search query has multiple words, use quotes |
763f653f | 123 | nimcoon "nim lang" |
f135dfc7 | 124 | |
763f653f | 125 | # Play audio of the first search result |
3c20e75c | 126 | nimcoon -m -l "counting stars" |
763f653f JN |
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 | |
44978125 | 136 | ``` |
c4aeb618 | 137 | |
763f653f JN |
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 | |
4827df7a | 146 | |
81fb030b | 147 | Nimcoon provides both interactive and non-interactive arguments with significant |
9ed70b9e JN |
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 | | |
5f9cdfef | 160 | | -a, --auto-play | Play the next search result (YouTube only) | |
4827df7a | 161 | |
81fb030b | 162 | Feel free to use these options in any combination. Nimcoon will show a helpful |
763f653f JN |
163 | error message if you pick incompatible options. |
164 | ||
9ed70b9e JN |
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 | ||
5f9cdfef JN |
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 | ||
81fb030b | 181 | Auto-playing videos leads to binge watching. The default option in Nimcoon is to |
5f9cdfef | 182 | support auto-play for music only. |
9ed70b9e | 183 | |
3f6de5cb JN |
184 | ## Development |
185 | ||
186 | One-liner for compiling and running | |
c4aeb618 JN |
187 | |
188 | ```sh | |
763f653f | 189 | nim c -d:ssl -r src/nimcoon.nim 'nim lang' |
68fd8100 | 190 | ``` |
e26cfd93 JN |
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 | ``` | |
ca251617 | 210 |