Rebrand NimCoon to Nimcoon
[nimcoon.git] / README.md
CommitLineData
81fb030b 1# Nimcoon
726cf1a7 2
cc78bba9 3Play videos from YouTube and PeerTube from the command line using your preferred desktop media player.
44978125 4
cc78bba9 5Similar 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
10This 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
16A Maine Coon cat wearing a golden crown.
17Logo contributions/suggestions welcome.
18
19Maybe 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
25I 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
29YouTube'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 31Nimcoon 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
33I 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
37I 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 73Nim Coon depends on the following:
7d08d1af
JN
74- youtube-dl
75- mpv (recommended) or vlc
8d06ad69 76- peerflix and webtorrent (for magnet links)
7d08d1af 77
8d06ad69 78Install MPV or VLC using your distribution's package manager.
88a5646a
JN
79
80Install YouTube-dl
81``` sh
82pip3 install --user youtube-dl
83```
84
8d06ad69 85Install PeerFlix and WebTorrent
88a5646a 86```sh
0c2f0385 87npm install --global peerflix 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 94Nimcoon can be installed from Nimble repositories:
af9a966f
JN
95
96``` sh
97nimble install nimcoon
98```
99
100You can also install from source by running the following command:
44978125 101
c4aeb618 102```sh
af9a966f 103nimble install
c4aeb618
JN
104```
105
af9a966f 106### Installing binary
44978125 107
af9a966f 108Download the latest build from GitlabCI (amd64 GNU/Linux only).
44978125 109
3f6de5cb 110```sh
af9a966f
JN
111wget https://gitlab.com/njoseph/nimcoon/-/jobs/artifacts/master/download?job=compile -O artifacts.zip
112unzip artifacts.zip
44978125
JN
113```
114
af9a966f
JN
115Copy the binary to somewhere on your path like /usr/local/bin
116
3f6de5cb 117## Usage
44978125
JN
118
119```sh
763f653f 120nimcoon "emacs"
44978125 121
c4aeb618 122# If your search query has multiple words, use quotes
763f653f 123nimcoon "nim lang"
f135dfc7 124
763f653f 125# Play audio of the first search result
3c20e75c 126nimcoon -m -l "counting stars"
763f653f
JN
127
128# Download audio of the first search result
129nimcoon -mld "counting stars"
130
131# Play direct video link
132nimcoon https://www.youtube.com/watch?v=QOEMv0S8AcA
133
134# Add -d to download or -m to select only audio or both
135nimcoon -md https://www.youtube.com/watch?v=hT_nvWreIhg
44978125 136```
c4aeb618 137
763f653f
JN
138After the search results are displayed, you can enter a number to play one
139result, "all" to play all the results or "q" to quit the program.
140
141If a number is entered, after the selected search result is played, the results
142are redisplayed, so that you can play the other results without having to search
143again.
144
145### Command line arguments
4827df7a 146
81fb030b 147Nimcoon provides both interactive and non-interactive arguments with significant
9ed70b9e
JN
148overlap. But some arguments might only be present in one mode.
149
150Non-interactive arguments are specified to the nimcoon program and apply
151globally to all search results in that session. These can be overriden on a
152case-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 162Feel free to use these options in any combination. Nimcoon will show a helpful
763f653f
JN
163error message if you pick incompatible options.
164
9ed70b9e
JN
165Interactive arguments are provided during selection of a search result. These
166options allow you to change your mind after performing the search. For example,
167you might have searched for a music video, watched it and want to download the
168music only. In this case, you can specify the search result followed by the
169options 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 181Auto-playing videos leads to binge watching. The default option in Nimcoon is to
5f9cdfef 182support auto-play for music only.
9ed70b9e 183
3f6de5cb
JN
184## Development
185
186One-liner for compiling and running
c4aeb618
JN
187
188```sh
763f653f 189nim c -d:ssl -r src/nimcoon.nim 'nim lang'
68fd8100 190```
e26cfd93
JN
191
192## Privacy
193
194To avoid storing your nimcoon searches in `zsh` history, run this command
195
196```sh
197setopt histignorespace
198```
199
200Then, add a space before typing nimcoon in the shell, like " nimcoon"
201
202```sh
203 nimcoon "this is private"
204```
205
206The same can be achieved in `bash` by setting an environment variable
207```sh
208export HISTCONTROL=ignoreboth
209```
ca251617 210