2022-09-16 15:52:59 -04:00
## About
2023-09-10 21:29:11 -04:00
Sometimes, you just need a way to randomly display media from your filesystem.
2022-09-16 15:52:59 -04:00
2022-10-18 17:58:15 -04:00
Simply point this tool at one or more directories, and then open the specified port (default `8080` ) in your browser.
2022-09-16 15:52:59 -04:00
2023-09-10 21:29:11 -04:00
A new file will be selected if you open `/` directly, or if you click on any displayed files.
2022-09-16 15:52:59 -04:00
2023-09-10 21:29:11 -04:00
Browser history is preserved, so you can always go back to any previously displayed media.
2022-09-16 15:52:59 -04:00
2023-09-11 22:24:25 -04:00
Supported file types and extensions are listed in the corresponding source files in `formats/` .
2022-10-18 17:58:15 -04:00
2022-11-11 00:33:20 -05:00
Feature requests, code criticism, bug reports, general chit-chat, and unrelated angst accepted at `roulette@seedno.de` .
2022-11-11 00:34:31 -05:00
Static binary builds available [here ](https://cdn.seedno.de/builds/roulette ).
2022-11-11 18:51:02 -05: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` .
2023-09-05 11:20:04 -04:00
Dockerfile available [here ](https://git.seedno.de/seednode/roulette/raw/branch/master/docker/Dockerfile ).
2022-09-16 15:52:59 -04:00
2022-10-19 20:56:42 -04:00
## Filtering
2022-11-10 15:54:55 -05: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-19 20:56:42 -04:00
Only filenames matching one or more of the patterns will be served.
2022-11-10 15:54:17 -05:00
You can also provide a comma-delimited string of alphanumeric patterns to exclude, via the `exclude=` query parameter.
2022-10-19 20:56:42 -04:00
Filenames matching any of these patterns will not be served.
2023-01-18 12:20:47 -05:00
You can also combine these two parameters, with exclusions taking priority over inclusions.
2022-10-19 20:56:42 -04:00
Both filtering parameters ignore the file extension and full path; they only compare against the bare filename.
## Sorting
2022-10-19 21:37:12 -04:00
You can specify a sorting pattern via the `sort=` query parameter, assuming the `-s|--sort` flag is enabled.
2022-10-19 20:56:42 -04:00
2022-10-19 21:42:08 -04:00
A value of `sort=asc` means files will be served in ascending order (lowest-numbered to highest).
2022-10-19 20:56:42 -04:00
If a file exists with a numbered suffix one higher than the currently displayed file, it will be served next.
2022-11-10 15:54:17 -05:00
A value of `sort=desc` means files will be served in descending order (highest-numbered to lowest).
2022-10-19 20:56:42 -04: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-19 21:42:08 -04:00
For `sort=asc` , the lowest-numbered file matching a given name will be served first.
2022-10-19 20:56:42 -04:00
2022-10-19 21:42:08 -04:00
For `sort=desc` , the highest-numbered file will be served instead.
2022-10-19 20:56:42 -04:00
2022-10-19 21:42:08 -04: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-19 20:56:42 -04:00
2022-11-08 20:24:49 -05:00
## Refresh
2023-01-18 11:57:55 -05:00
If a positive-value `refresh=<integer><unit>` query parameter is provided, the page will reload after that interval.
2022-11-08 20:24:49 -05:00
2023-05-08 21:05:10 -04:00
This can be used to generate a sort of slideshow of files.
2022-11-08 20:24:49 -05:00
2023-08-21 16:38:56 -04:00
Minimum accepted value is 500ms, as anything lower seems to cause inconsistent behavior. This might be changed in a future release.
2023-01-18 10:58:14 -05:00
Supported units are `ns` , `us` /`µs`, `ms` , `s` , `m` , and `h` .
2023-01-18 13:11:23 -05:00
## Caching
2023-01-19 16:00:29 -05:00
If the `-c|--cache` flag is passed, the indices of all specified paths will be cached on start.
2023-01-18 13:11:23 -05: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-06-03 19:09:17 -04:00
The cache can be regenerated at any time by accessing the `/clear_cache` endpoint.
2023-01-18 13:11:23 -05:00
2023-02-05 15:37:25 -05:00
If `--cache-file` is set, the cache will be loaded from the specified file on start, and written to the file whenever it is re-generated.
2023-02-05 15:34:22 -05:00
2023-09-12 23:35:15 -04:00
If the `-i|--index` flag is passed, four additional endpoints are registered.
2023-09-12 15:00:15 -04:00
2023-09-12 23:35:15 -04:00
The first of these—`/html` and `/json` —return the contents of the index, in HTML and JSON formats respectively.
This can prove useful when confirming whether the index is generated successfully, or whether a given file is in the index.
The other two endpoints—`/extensions` and `/mime_types` —return the registered file types.
2023-09-12 15:00:15 -04:00
2023-02-05 15:42:31 -05:00
## Statistics
2023-01-19 13:07:15 -05:00
2023-06-03 19:09:17 -04:00
If the `--stats` flag is passed, an additional endpoint, `/stats` , is registered.
2023-01-19 13:07:15 -05:00
2023-01-21 11:27:35 -05: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 13:07:15 -05:00
2023-09-09 22:28:24 -04:00
## Russian
2023-09-09 22:27:57 -04:00
If the `--russian` flag is passed, everything functions exactly as you would expect.
That is, files will be deleted after being served. This is not a joke, you *will* lose data.
This uses `os.Remove()` and checks to ensure the specified file is inside one of the paths passed to `roulette` .
That said, this has not been tested to any real extent, so only pass this flag on systems you don't care about.
Enjoy!
2022-09-16 15:52:59 -04:00
## Usage output
```
2023-09-10 21:29:11 -04:00
Serves random media from the specified directories.
2023-08-02 14:29:37 -04:00
2023-02-05 15:42:31 -05:00
Usage:
2023-01-19 13:12:40 -05:00
roulette < path > [path]... [flags]
2022-09-16 15:52:59 -04:00
Flags:
2023-09-11 20:11:45 -04:00
--all enable all supported file types
2023-09-10 22:05:35 -04:00
--audio enable support for audio files
2023-08-21 16:38:56 -04:00
-b, --bind string address to bind to (default "0.0.0.0")
-c, --cache generate directory cache at startup
--cache-file string path to optional persistent cache file
-f, --filter enable filtering
2023-09-12 17:41:28 -04:00
--flash enable support for shockwave flash files (via ruffle.rs)
2023-08-21 16:38:56 -04:00
-h, --help help for roulette
2023-09-12 17:41:28 -04:00
--images enable support for image files
2023-09-12 14:20:38 -04:00
-i, --index expose index endpoints
2023-09-12 17:46:58 -04:00
--maximum-files uint32 skip directories with file counts above this value (default 4294967295)
--minimum-files uint32 skip directories with file counts below this value (default 1)
--page-length uint32 pagination length for statistics and debug pages
2023-08-21 16:38:56 -04:00
-p, --port uint16 port to listen on (default 8080)
2023-09-08 01:51:13 -04:00
--profile register net/http/pprof handlers
2023-08-21 16:38:56 -04:00
-r, --recursive recurse into subdirectories
--refresh-interval string force refresh interval equal to this duration (minimum 500ms)
2023-09-10 22:05:35 -04:00
--russian remove selected images after serving
2023-08-21 16:38:56 -04:00
-s, --sort enable sorting
--stats expose stats endpoint
--stats-file string path to optional persistent stats file
2023-09-11 21:02:52 -04:00
--text enable support for text files
2023-08-21 16:38:56 -04:00
-v, --verbose log accessed files to stdout
-V, --version display version and exit
2023-09-10 22:08:51 -04:00
--video enable support for video files
2023-09-05 09:22:06 -04:00
```
## Building the Docker container
From inside the `docker/` subdirectory, build the image using the following command:
2023-09-05 11:20:04 -04:00
`REGISTRY=<registry url> LATEST=yes TAG=alpine ./build.sh`