README: Add info about logo and alternatives
[nimcoon.git] / 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 - [ ] 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
70 ## Installation
71
72 Nim Coon depends on the following:
73 - youtube-dl
74 - mpv (recommended) or vlc
75 - peerflix and webtorrent (for magnet links)
76
77 Install MPV or VLC using your distribution's package manager.
78
79 Install YouTube-dl
80 ``` sh
81 pip3 install --user youtube-dl
82 ```
83
84 Install PeerFlix and WebTorrent
85 ```sh
86 npm install --global peerflix webtorrent-cli
87 ```
88
89 (Optional) If you want your YouTube downloads to be faster, install `aria2` download manager.
90
91 ### Installing using Nimble
92
93 NimCoon can be installed from Nimble repositories:
94
95 ``` sh
96 nimble install nimcoon
97 ```
98
99 You can also install from source by running the following command:
100
101 ```sh
102 nimble install
103 ```
104
105 ### Installing binary
106
107 Download the latest build from GitlabCI (amd64 GNU/Linux only).
108
109 ```sh
110 wget https://gitlab.com/njoseph/nimcoon/-/jobs/artifacts/master/download?job=compile -O artifacts.zip
111 unzip artifacts.zip
112 ```
113
114 Copy the binary to somewhere on your path like /usr/local/bin
115
116 ## Usage
117
118 ```sh
119 nimcoon "emacs"
120
121 # If your search query has multiple words, use quotes
122 nimcoon "nim lang"
123
124 # Play audio of the first search result
125 nimcoon -m -l "counting stars"
126
127 # Download audio of the first search result
128 nimcoon -mld "counting stars"
129
130 # Play direct video link
131 nimcoon https://www.youtube.com/watch?v=QOEMv0S8AcA
132
133 # Add -d to download or -m to select only audio or both
134 nimcoon -md https://www.youtube.com/watch?v=hT_nvWreIhg
135 ```
136
137 After the search results are displayed, you can enter a number to play one
138 result, "all" to play all the results or "q" to quit the program.
139
140 If a number is entered, after the selected search result is played, the results
141 are redisplayed, so that you can play the other results without having to search
142 again.
143
144 ### Command line arguments
145
146 | **Arguments** | **Explanation** |
147 |-------------------|--------------------------------------------|
148 | -m, --music | Play Music only, no video |
149 | -l, --lucky | Try your luck with the first search result |
150 | -f, --full-screen | Play video in full screen |
151 | -d, --download | Download video or music |
152
153 Feel free to use these options in any combination. NimCoon will show a helpful
154 error message if you pick incompatible options.
155
156 ## Development
157
158 One-liner for compiling and running
159
160 ```sh
161 nim c -d:ssl -r src/nimcoon.nim 'nim lang'
162 ```
163
164 ## Privacy
165
166 To avoid storing your nimcoon searches in `zsh` history, run this command
167
168 ```sh
169 setopt histignorespace
170 ```
171
172 Then, add a space before typing nimcoon in the shell, like " nimcoon"
173
174 ```sh
175 nimcoon "this is private"
176 ```
177
178 The same can be achieved in `bash` by setting an environment variable
179 ```sh
180 export HISTCONTROL=ignoreboth
181 ```
182