diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 59 |
1 files changed, 51 insertions, 8 deletions
@@ -11,26 +11,30 @@ Once configured, a request of the form `http://localhost:9999/<last.fm username> 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. +*** + ### `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_WHITELIST_MODE` (Default: open) +### `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: "") +### `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") +### `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 @@ -38,25 +42,60 @@ 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") +### `LFME_DEFAULT_REFRESH` (Default: `"5m"`) The amount of time to cache non-whitelisted user info for. See `LFME_WHITELIST_REFRESH` for more info. -### `LFME_PORT` (Default: 9999) +### `LFME_PORT` (Default: `9999`) The port to serve on locally. -### `LFME_THEMES_DIR` -If set, must be a valid path to a directory containing CSS files. +### `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. -### `LFME_LOG_LEVEL` (Default: Warn) +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`. + +### `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. + +### `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`. +### `LFME_NO_REFRESH` (Default: `0`) +If set to `1`, disable outputting of the HTML `meta http-eqiv="refresh"` tag, used for live status updates. + ## Example Configuration ```ini LFME_API_KEY=0123456789abcdef0123456789abcdef @@ -67,3 +106,7 @@ LFME_WHITELIST_REFRESH=30s LFME_WHITELIST_MODE=exclusive LFME_WHITELIST=a_precious_basket_case, realRiversCuomo, Pixiesfan12345 ``` +*** + +## Theming + |