2022-09-16 19:52:59 +00:00
## About
2022-10-18 21:58:15 +00:00
Sometimes, you just need a way to randomly display images from your filesystem.
2022-09-16 19:52:59 +00:00
2022-10-18 21:58:15 +00:00
Simply point this tool at one or more directories, and then open the specified port (default `8080` ) in your browser.
2022-09-16 19:52:59 +00:00
2022-10-18 21:58:15 +00:00
A new image will be selected if you open `/` directly, or if you click on any displayed image.
2022-09-16 19:52:59 +00:00
Browser history is preserved, so you can always go back to any previously displayed image.
2022-10-31 20:18:47 +00:00
Supported file types and extensions are `bmp` , `gif` , `jp[e]g` , `png` , and `webp` .
2022-10-18 21:58:15 +00:00
2022-11-11 05:33:20 +00:00
Feature requests, code criticism, bug reports, general chit-chat, and unrelated angst accepted at `roulette@seedno.de` .
2022-11-11 05:34:31 +00:00
Static binary builds available [here ](https://cdn.seedno.de/builds/roulette ).
2022-11-11 23:51:02 +00:00
I only test the linux/amd64, linux/arm64, and windows/amd64 builds, the rest are all best-effort™.
x86_64 and ARM Docker images of latest version: `oci.seedno.de/seednode/roulette:latest` .
Dockerfile available [here ](https://git.seedno.de/seednode/docker-roulette ).
2022-09-16 19:52:59 +00:00
2022-10-20 00:56:42 +00:00
## Filtering
2022-11-10 20:54:55 +00:00
You can provide a comma-delimited string of alphanumeric patterns to match via the `include=` query parameter, assuming the `-f|--filter` flag is enabled.
2022-10-20 00:56:42 +00:00
Only filenames matching one or more of the patterns will be served.
2022-11-10 20:54:17 +00:00
You can also provide a comma-delimited string of alphanumeric patterns to exclude, via the `exclude=` query parameter.
2022-10-20 00:56:42 +00:00
Filenames matching any of these patterns will not be served.
2023-01-18 17:20:47 +00:00
You can also combine these two parameters, with exclusions taking priority over inclusions.
2022-10-20 00:56:42 +00:00
Both filtering parameters ignore the file extension and full path; they only compare against the bare filename.
## Sorting
2022-10-20 01:37:12 +00:00
You can specify a sorting pattern via the `sort=` query parameter, assuming the `-s|--sort` flag is enabled.
2022-10-20 00:56:42 +00:00
2022-10-20 01:42:08 +00:00
A value of `sort=asc` means files will be served in ascending order (lowest-numbered to highest).
2022-10-20 00:56:42 +00:00
If a file exists with a numbered suffix one higher than the currently displayed file, it will be served next.
2022-11-10 20:54:17 +00:00
A value of `sort=desc` means files will be served in descending order (highest-numbered to lowest).
2022-10-20 00:56:42 +00:00
If a file exists with a numbered suffix one lower than the currently displayed file, it will be served next.
In either case, if no sequential file is found, a new random one will be chosen.
2022-10-20 01:42:08 +00:00
For `sort=asc` , the lowest-numbered file matching a given name will be served first.
2022-10-20 00:56:42 +00:00
2022-10-20 01:42:08 +00:00
For `sort=desc` , the highest-numbered file will be served instead.
2022-10-20 00:56:42 +00:00
2022-10-20 01:42:08 +00:00
If any other (or no) value is provided, the selected file will be random.
Note: These patterns require sequentially-numbered files matching the following pattern: `filename###.extension` .
2022-10-20 00:56:42 +00:00
2022-11-09 01:24:49 +00:00
## Refresh
2023-01-18 16:57:55 +00:00
If a positive-value `refresh=<integer><unit>` query parameter is provided, the page will reload after that interval.
2022-11-09 01:24:49 +00:00
This can be used to generate a sort of slideshow of images.
2023-01-18 15:58:14 +00:00
Supported units are `ns` , `us` /`µs`, `ms` , `s` , `m` , and `h` .
2023-01-18 18:11:23 +00:00
## Caching
2023-01-19 21:00:29 +00:00
If the `-c|--cache` flag is passed, the indices of all specified paths will be cached on start.
2023-01-18 18:11:23 +00:00
This will slightly increase the delay before the application begins responding to requests, but should significantly speed up subsequent requests.
If any `include=` /`exclude=` filters are specified in a given request, the cache will be bypassed for that specific request.
2023-01-21 16:27:35 +00:00
The cache can be regenerated at any time by accessing the `/_/clear_cache` endpoint.
2023-01-18 18:11:23 +00:00
2023-01-19 18:07:15 +00:00
## Debug
2023-01-21 16:27:35 +00:00
If the `-d|--debug` flag is passed, an additional endpoint, `/_/stats` , is registered.
2023-01-19 18:07:15 +00:00
2023-01-21 16:27:35 +00:00
When accessed, this endpoint returns a JSON document listing every file served, along with the number of times it has been served, its filesize, and timestamps of when it was served.
2023-01-19 18:07:15 +00:00
2022-09-16 19:52:59 +00:00
## Usage output
```
Usage:
2023-01-19 18:12:40 +00:00
roulette < path > [path]... [flags]
2022-09-16 19:52:59 +00:00
roulette [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
version Print version
Flags:
2023-02-05 05:44:31 +00:00
-c, --cache generate directory cache at startup
-d, --debug expose stats endpoint
-f, --filter enable filtering
-h, --help help for roulette
-i, --index string path to persistent index file
-p, --port uint16 port to listen on (default 8080)
-r, --recursive recurse into subdirectories
-s, --sort enable sorting
-v, --verbose log accessed files to stdout
2022-09-16 19:52:59 +00:00
Use "roulette [command] --help" for more information about a command.
2023-01-20 02:57:18 +00:00
```
