-
Notifications
You must be signed in to change notification settings - Fork 10
/
Copy pathiheart-url.1
140 lines (140 loc) · 3.81 KB
/
iheart-url.1
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
.Dd
.Dt IHEART-URL 1
.Os
.Sh NAME
.Nm iheart-url
.Nd print the audio stream URL for an iheartradio station
.Sh SYNOPSIS
.Nm iheart-url
.Op Fl chiv
.Op Fl l Ar terms
.Op Fl s Ar terms
.Op station_id
.Nm iheart-mplayer
.Op Fl c
.Op Fl l Ar terms
.Op station_id
.Nm iheart-mpv
.Op Fl c
.Op Fl l Ar terms
.Op station_id
.Nm iheart-vlc
.Op Fl c
.Op Fl l Ar terms
.Op station_id
.Sh DESCRIPTION
.Nm
fetches the URL for an iHeartRadio station's audio stream from iHeartRadio's
API servers and prints it to stdout.
It is meant to be used with audio players and the command substitution syntax in
most shells, like so:
.Bd -literal -offset -indent
$ mplayer -novideo "$(iheart-url [station_id])"
.Ed
.Pp
.Nm iheart-mplayer
is a trivial POSIX sh wrapper scripts that does precisely that for the
.Nm mplayer
media player, or for
.Nm mpv
or
.Nm vlc
if it is called by the corresponding names.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl c
Disable TLS; all API requests will be done in cleartext, and only cleartext
stream URLS will be returned.
May prevent any valid stream URL from being returned, in the event that the
station has only TLS streams.
.It Fl h
Display a help message.
Meaningless for wrapper scripts.
.It Fl i
Instead of printing the URL for a station, output some human-readable info about
it.
Meaningless for wrapper scripts.
.It Fl l Ar terms
.Dq I'm feeling lucky
search for terms; print the URL of the
.Dq best
result according to iHeartRadio's servers.
.It Fl s Ar terms
Run a search for terms, outputting vital information like station ID for each
result.
Meaningless for wrapper scripts.
.It Fl v
Increase verbosity level, may be specified multiple times for more verbosity.
Useful in conjunction with
.Fl s .
Meaningless for wrapper scripts.
.It station_id
Print the URL for this numerical station ID.
Station IDs can be obtained with
.Fl i
or
.Fl s .
.El
.Sh ENVIRONMENT
.Bl -hang -width "PLAYER_OPTSXX" -compact
.It Ev MPLAYER_OPTS
.It Ev MPV_OPTS
.It Ev VLC_OPTS
Command line arguments for wrapper scripts to pass their players.
.El
.Sh EXAMPLES
Print the URL for station ID 5361:
.Bd -literal -offset -indent
$ iheart-url 5361
.Ed
.Pp
Print expanded search results for the term
.Dq Sports:
.Bd -literal -offset -indent
$ iheart-url -vs Sports
.Ed
.Pp
Play the best match for the search term
.Dq Classic rock
in mpv
.Pq note the use of double quotes to prevent the shell from field-splitting the search term:
.Bd -literal -offset -indent
$ iheart-mpv -l "Classic rock"
.Ed
.Sh CAVEATS
While most media players capable of handling network streams will be able to use
these URLs, the lack of public documentation concerning iHeartRadio's API
precludes any guarantees about the content provided.
Also because of the lack of documentation, much of this tool's functionality
relies on information gained from deep-packet inspection of official iHeartRadio
apps' traffic and on trial and error.
The iHeartRadio API has been known to change on occasion and break iheart-url's
functionality.
Technical documentation derived from this tool's development may be found in its
source code and in the 'iheart-api' file in the source distribution.
.Sh BUGS
.Nm iheart-mplayer ,
.Nm iheart-mpv ,
and
.Nm iheart-vlc
naively pass all their arguments to iheart-url, and all of iheart-url's stdout
output as an argument to the player.
Players do not particularly like the output of
.Fl h ,
.Fl i ,
or
.Fl s .
.Pp
Multiple people have reported intermittent outages of the iHeartRadio API,
during which it may return HTTP errors for iheart-url's requests for certain
stations.
.Pp
Python may raise string encoding exceptions if the console does not support
UTF-8.
Setting
.Ev PYTHONIOENCODING
to something like ":namereplace" in the environment is recommended.
.Pp
Up-to-date information on any issues can be found on the Github issue tracker:
https://github.com/oldlaptop/iheart-mplayer/issues