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