« get me outta code hell

README.md - http-music - Command-line music player + utils (not a server!)
about summary refs log tree commit diff
path: root/README.md
blob: 2ded9a6f8944856429805fc9752c49b9e73a1353 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
# `http-music`

![Play demo](screenshots/hm-basic-usage.png)
![Local crawl demo](screenshots/hm-crawllocal.png)

A command line program that lets you download music from places (like the
internet, or your hard drive) and play it. It's also
[decently powerful](#screenshots).

## Installation

```bash
$ git clone https://github.com/towerofnix/http-music
$ cd http-music
$ npm install

# Installs http-music GLOBALLY, i.e., so you can use from in any directory.
$ npm link # (You might need sudo here.)

# (Hey, you! That one person who only reads the install code! Please also
# read the "you will also need" section below.)
```

**You will also need:**

* **A player:** [`play` (from SoX)][sox] and [`mpv`][mpv] both work. You'll
  only need one of these, but mpv gives you access to play/pause and seeking
  controls.

* **A sound converter:** either [`avconv`][libav] or [`ffmpeg`][ffmpeg] will
  work.

* **Optionally,** [`youtube-dl`][ytdl] lets you [play][apply] music from
  [just about anywhere][moresites] (rather than just
  `http://blah/foo.mp3`-like URLs!).

There's a fair chance you already have some of these installed; you can always
check from your terminal using the [`type`][type] command!

## Usage

```
# Generate a playlist file, using the handy interactive setup utility..
$ http-music setup

# ..or one of these shell commands:
$ http-music crawl-http http://some.directory.listing.server/ > playlist.json
$ http-music crawl-local ~/Music/ > playlist.json

# Then play it:
$ http-music play

# (You can use `python3 -m http.server` or `python2 -m SimpleHTTPServer` to
# run a quick and easy directory listing, to pass into crawl-http!)
```

## Screenshots

**Super-basic usage (`http-music play`):**

![Basic usage](screenshots/hm-basic-usage.png)

**Load music from the file system (`http-music crawl-local . > playlist.json`):**

![Local crawl](screenshots/hm-crawllocal.png)

**Load music from an HTTP server (<code>http-music crawl-http http://<a href="https://stackoverflow.com/q/7943751/4633828">some.directory.listing</a></code>):**

![Crawl HTTP](screenshots/hm-remote.png)

**Filter by a specific group (`http-music play --clear --keep 'C418/one'`):**

(A shorthand also works! Try `http-music play -c -k C418/one`.)

![Clear/keep](screenshots/hm-clearkeep.png)

## Documentation

Check out [the man pages](man/). (Or view them with `man http-music`.)

  [sox]: http://sox.sourceforge.net/
  [mpv]: https://mpv.io/
  [libav]: https://www.libav.org/
  [ffmpeg]: https://www.ffmpeg.org/
  [type]: https://unix.stackexchange.com/a/10529/125775
  [ytdl]: http://rg3.github.io/youtube-dl/
  [moresites]: http://rg3.github.io/youtube-dl/supportedsites.html
  [apply]: https://gist.github.com/towerofnix/cd7465a82c8b367eef221e61c3b6186e