aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
blob: 8095b5a2d46d128d854493787fc66057d43005c2 (plain) (blame)
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
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
# `lfm_embed`
A simple webserver for rendering a last.fm embed.

More specifically, this displays a simple webpage with info about your current or most recent last.fm scrobble.
Its intended use is to be put in an iframe on a personal site or whatever.
While it is self-hostable, there is an official public instance at [scrobble.observer](https://scrobble.observer).

Release builds available [here](https://aleteoryx.me/downloads2/lfm_embed).

# Usage

`lfm_embed` serves one thing:
Requests to `/user/<last.fm username>` will generate a page displaying your current or last last.fm scrobble.
The look and feel of this is down to the configured theme for your request.

As the user, you may select a theme supported by the server by passing `?theme=` query string.
Check with your host for a list of supported themes.

Individual themes may also support parameters, via additional query parameters.

## Builtin Themes

### `plain`

A minimal theme, displaying just the username, album art, and track info.
It is the default fallback for an unset or unknown theme.

![A screenshot of the plain theme, displaying album art, and the text "@vvinrg is scrobbling Sweet Tooth from Sleepyhead by Cavetown".](screenshots/plain-light.png)

#### Parameters

- `?dark`: toggle the theme's dark mode.

# Self-Hosting
`lfm_embed` is, as it stands, designed to use a reverse proxy.
A future release may include HTTPS support, but currently, it will only listen on `localhost`, prohibiting it from public access.
Once configured, a request of the form `http://localhost:9999/user/<last.fm username>` will render out an embed with the default theme.

As it stands, there are no plans to support displaying users with private listen history.

# Configuration
Configuration should be done via the environment.
`lfm_embed` also supports reading from a standard `.env` file.
The following are the environment variables which `lfm_embed` understands.

## Core Config

### `LMFE_API_KEY` (Required)
Your last.fm API key. You'll need to create one [here](https://www.last.fm/api/account/create) for self-hosting.

### `LFME_PORT` (Default: `9999`)
The port to serve on locally.

### `LFME_NO_REFRESH` (Default: `0`)
If set to `1`, disable outputting of the HTTP `Refresh: <cache refresh>` header, used to provide live status updates.

## Logging

### `LFME_LOG_LEVEL` (Default: `"warn"`)
The loglevel. This is actually parsed as an [`env_logger`](https://docs.rs/env_logger/latest/env_logger) filter string.
Read the docs for more info.

### `LFME_LOG_FILE`
If set, logs will be written to the specified file. Otherwise, logs are written to `stderr`.

## User Perms

### `LFME_WHITELIST_MODE` (Default: `"open"`)
The following(case-insensitive) values are supported:

- `open`: Allow requests for all users.

- `exclusive`: Only allow requests for users in `LFME_WHITELIST`, returning HTTP 403 for all others. `LFME_WHITELIST` _must_ be set if this mode is enabled.

If the user requested has their listen history private, a 403 will be returned.

### `LFME_WHITELIST` (Default: `""`)
This is expected to be a sequence of comma-separated usernames.
Leading/trailing whitespace will be stripped, and unicode is fully supported.

### `LFME_WHITELIST_REFRESH` (Default: `"1m"`)
The amount of time to cache whitelisted user info for.
It is interpreted as a sequence of `<num><suffix>` values, where `num` is a positive integer,
and `suffix` is one of `y`,`mon`,`w`,`d`,`h`,`m`,`s`, `ms`, `µs`, or `ns`, each of which
corresponds to a self-explanatory unit of time.
For most practical applications, one should only use `m` and `s`, as caching your current listen for more than that time has the potential to omit most songs.
Parsing is delegated to the [`duration_str`](https://docs.rs/duration-str/latest/duration_str/) crate, and further info may be found there.

### `LFME_DEFAULT_REFRESH` (Default: `"5m"`)
The amount of time to cache non-whitelisted user info for.
See `LFME_WHITELIST_REFRESH` for more info.

## Themes

### `LFME_THEME_DIR`
If set, must be a valid path to a directory containing [Handlebars](https://handlebarsjs.com/guide/#language-features) files, ending in LFME_THEME_EXT.
They will be registered as themes on top of the builtin ones, with each theme's name being their filename minus the extension.
Same-named themes will override builtin ones.

See [Theming](#theming) for details on writing custom themes.

Theme names are the same as their path, minus the extension. Given an extension of .hbs, a directory like:
```
themes/
  mytheme.hbs
  myothertheme.hbs
  myunrelatedfile.css
  alices-themes/
    mytheme.hbs
    mysuperawesometheme.hbs
```
results in the following themes:
```
mytheme
myothertheme
alices-themes/mytheme
alices-themes/mysuperawesometheme
```

By default, these are loaded and compiled once, at startup.

### `LFME_THEME_EXT` (Default: `.hbs`)
The file extension for themes in `LFME_THEME_DIR`.

Note: This behaves more like a suffix than a file extension. You must include the leading dot for a file extension.

### `LFME_THEME_DEV` (Default: `0`)
If set to `1`, existing themes will be reloaded on edit.

Note: Even with this mode, adding a new theme requires a full reload.
Themes are only enumerated once, at startup. (This is a limitation of the [`handlebars`](https://docs.rs/handlebars/latest/handlebars) implementation in use, and may change.)

### `LFME_THEME_DEFAULT` (Default: `"plain"`)
The theme to use when no query string is present.

## Example Configuration
```ini
LFME_API_KEY=0123456789abcdef0123456789abcdef
LFME_LOG_LEVEL=error
LFME_PORT=3000

LFME_WHITELIST_REFRESH=30s
LFME_WHITELIST_MODE=exclusive
LFME_WHITELIST=a_precious_basket_case, realRiversCuomo, Pixiesfan12345
```

# Theming {#theming}

Custom themes are, as stated above, [Handlebars](https://handlebarsjs.com/guide/#language-features) files.
They are expected to produce a complete HTML doc, which should contain info about a user's scrobbles.

See `src/themes` for examples of implementation.

## Writing a Theme

Themes should have, roughly, the structure below:

```html
<!DOCTYPE html>
<html lang="en"> <!-- Or really whatever you want, but I speak English. -->
    <head>
        <meta charset="UTF-8">
        <style> /* styles */ </style>
    </head>
    <body>
        {{#if error}}<p>{{error}}</p>{{else}}
            <!-- theme contents here -->
        {{/if}}
    </body>
</html>
```

You will be passed one of 2 context objects, depending on if there was an error processing the request.
If there was an error, the object will just be `{ error: String }`, otherwise it will be the following:

```js
{
    // The user the request was made on the behalf of.
    user: {
        // Their username.
        name: String,
        // Their "Display Name".
        realname: String,
        // Link to user's profile picture.
        image_url: String,
        // Link to user's profile.
        url: String,
        
        // Total scrobbles.
        scrobble_count: Number,
        // Number of artists in library.
        artist_count: Number,
        // Number of tracks in library.
        track_count: Number,
        // Number of albums in library.
        album_count: Number,
        
        // True if user subscribes to last.fm pro.
        pro_subscriber: Boolean
    },
    
    // The user's most current, or most scrobble.
    scrobble: {
        // The name of the track.
        name: String,
        // The name of its album.
        album: String,
        // The artist who made it.
        artist: {
            // Their name.
            name: String,
            // Link to their profile image.
            image_url: String,
            // Link to the artist's last.fm page.
            url: String
        },
        // A link to the track image.
        image_url: String,
        // A link to the track's last.fm page.
        url: String,

        // True if the user has loved the track.
        loved: Boolean
        // True if the user is currently scrobbling it, false if it's just
        // the most recently played track.
        now_playing: Boolean,
    },
    
    // A set of extraneous query parameters.
    //
    // This should be considered UNTRUSTED, as the requester has full
    // control over it. Use the provided `html_escape`,
    // `html_attr_escape`, and `uri_encode` helpers when inlining
    // any contained text.
    query: Object
}
```

In addition, the following [helpers](https://handlebarsjs.com/guide/expressions.html#helpers) are provided, on top of the handlebars [builtins](https://handlebarsjs.com/guide/builtin-helpers.html):

- `(eq Object Object) => Boolean`: Check equality between its args.

- `(ne Object Object) => Boolean`: Check inequality between its args.

- `(gt Number|String Number|String) => Boolean`: Check if the first arg is greater than the second.

- `(gte Number|String Number|String) => Boolean`: Check if the first arg is greater than or equal to the second.

- `(lt Number|String Number|String) => Boolean`: Check if the first arg is less than the second.

- `(lte Number|String Number|String) => Boolean`: Check if the first arg is less than or equal to the second.

- `(and Boolean Boolean) => Boolean`: Boolean AND gate.

- `(or Boolean Boolean) => Boolean`: Boolean OR gate.

- `(not Boolean) => Boolean`: Boolean NOT gate.

- `(html_escape String) => String`: Escape HTML special characters from the input string, replacing them with HTML entities in the output. For use in standard markdown.

- `(html_attr_escape String) => String`: Escape HTML special characters, as well as quotation marks, in the input, replacing them with HTML entities and escaped quotes in the output. For use in HTML tag attributes.

- `(uri_encode String) => String`: URI-encode input text, making the output suitable to be included as part of a link or other URL.

# Contributing

[E-Mail me](mailto:alyx@aleteoryx.me) if you'd like to help out, submit a custom theme, or request a feature.

# Legal
```txt
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.
```