2022-09-16 19:52:59 +00:00
## About
2023-09-11 01:29:11 +00:00
Sometimes, you just need a way to randomly display media 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
2023-09-11 01:29:11 +00:00
A new file will be selected if you open `/` directly, or if you click on any displayed files.
2022-09-16 19:52:59 +00:00
2023-09-11 01:29:11 +00:00
Browser history is preserved, so you can always go back to any previously displayed media.
2022-09-16 19:52:59 +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` .
2023-09-05 15:20:04 +00:00
Dockerfile available [here ](https://git.seedno.de/seednode/roulette/raw/branch/master/docker/Dockerfile ).
2022-09-16 19:52:59 +00:00
2023-09-13 22:02:43 +00:00
## Caching
If the `-c|--cache` flag is passed, the indices of all specified paths will be cached on start.
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.
The cache can be regenerated at any time by accessing the `/clear_cache` endpoint.
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.
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.
2023-09-13 22:02:43 +00:00
## Info
2022-10-20 00:56:42 +00:00
2023-09-13 22:02:43 +00:00
If the `-i|--info` flag is passed, six additional endpoints are registered.
2022-10-20 00:56:42 +00:00
2023-09-13 22:02:43 +00:00
The first of these—`/html` and `/json` —return the contents of the index, in HTML and JSON formats respectively.
2022-10-20 00:56:42 +00:00
2023-09-13 22:02:43 +00:00
If `--page-length` is also set, these can be viewed in paginated form by appending `/n` , e.g. `/html/5` for the fifth page.
2022-10-20 00:56:42 +00:00
2023-09-13 22:02:43 +00:00
This can prove useful when confirming whether the index is generated successfully, or whether a given file is in the index.
2022-10-20 01:42:08 +00:00
2023-09-13 22:02:43 +00:00
The remaining four endpoints—`/available_extensions`, `/enabled_extensions` , `/available_mime_types` and `/enabled_mime_types` —return information about the registered file types.
2022-10-20 00:56:42 +00:00
2022-11-09 01:24:49 +00:00
## Refresh
2023-09-14 05:07:54 +00:00
If the `--refresh` flag is passed and 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
2023-05-09 01:05:10 +00:00
This can be used to generate a sort of slideshow of files.
2022-11-09 01:24:49 +00:00
2023-08-21 20:38:56 +00: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 15:58:14 +00:00
Supported units are `ns` , `us` /`µs`, `ms` , `s` , `m` , and `h` .
2023-09-13 22:02:43 +00:00
## Russian
If the `--russian` flag is passed, everything functions exactly as you would expect.
2023-02-05 20:34:22 +00:00
2023-09-13 22:02:43 +00:00
That is, files will be deleted after being served. This is not a joke, you *will* lose data.
2023-09-13 04:35:17 +00:00
2023-09-13 22:02:43 +00:00
This uses `os.Remove()` and checks to ensure the specified file is inside one of the paths passed to `roulette` .
2023-09-12 19:00:15 +00:00
2023-09-13 22:02:43 +00:00
That said, this has not been tested to any real extent, so only pass this flag on systems you don't care about.
2023-09-13 03:35:15 +00:00
2023-09-13 22:02:43 +00:00
Enjoy!
2023-09-13 04:35:17 +00:00
2023-09-13 22:02:43 +00:00
## Sorting
2023-09-13 03:35:15 +00:00
2023-09-13 22:02:43 +00:00
You can specify a sorting pattern via the `sort=` query parameter, assuming the `-s|--sort` flag is enabled.
2023-09-12 19:00:15 +00:00
2023-09-13 22:02:43 +00:00
A value of `sort=asc` means files will be served in ascending order (lowest-numbered to highest).
2023-01-19 18:07:15 +00:00
2023-09-13 22:02:43 +00:00
If a file exists with a numbered suffix one higher than the currently displayed file, it will be served next.
2023-01-19 18:07:15 +00:00
2023-09-13 22:02:43 +00:00
A value of `sort=desc` means files will be served in descending order (highest-numbered to lowest).
2023-01-19 18:07:15 +00:00
2023-09-13 22:02:43 +00:00
If a file exists with a numbered suffix one lower than the currently displayed file, it will be served next.
2023-09-13 04:35:17 +00:00
2023-09-13 22:02:43 +00:00
In either case, if no sequential file is found, a new random one will be chosen.
2023-09-10 02:27:57 +00:00
2023-09-13 22:02:43 +00:00
For `sort=asc` , the lowest-numbered file matching a given name will be served first.
2023-09-10 02:27:57 +00:00
2023-09-13 22:02:43 +00:00
For `sort=desc` , the highest-numbered file will be served instead.
2023-09-10 02:27:57 +00:00
2023-09-13 22:02:43 +00:00
If any other (or no) value is provided, the selected file will be random.
2023-09-10 02:27:57 +00:00
2023-09-13 22:02:43 +00:00
Note: These patterns require sequentially-numbered files matching the following pattern: `filename###.extension` .
2023-09-10 02:27:57 +00:00
2022-09-16 19:52:59 +00:00
## Usage output
```
2023-09-11 01:29:11 +00:00
Serves random media from the specified directories.
2023-08-02 18:29:37 +00:00
2023-02-05 20:42:31 +00:00
Usage:
2023-01-19 18:12:40 +00:00
roulette < path > [path]... [flags]
2022-09-16 19:52:59 +00:00
Flags:
2023-09-14 05:05:31 +00:00
-a, --all enable all supported file types
--audio enable support for audio files
-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
2023-09-14 22:37:22 +00:00
--code enable support for source code files
2023-09-14 05:05:31 +00:00
-f, --filter enable filtering
--flash enable support for shockwave flash files (via ruffle.rs)
--handlers display registered handlers (for debugging)
-h, --help help for roulette
--images enable support for image files
-i, --info expose informational endpoints
--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
-p, --port uint16 port to listen on (default 8080)
--prefix string root path for http handlers (for reverse proxying) (default "/")
--profile register net/http/pprof handlers
-r, --recursive recurse into subdirectories
2023-09-14 05:07:54 +00:00
--refresh enable automatic page refresh via query parameter
2023-09-14 05:05:31 +00:00
--russian remove selected images after serving
-s, --sort enable sorting
--text enable support for text files
-v, --verbose log accessed files and other information to stdout
-V, --version display version and exit
--video enable support for video files
2023-09-05 13:22:06 +00:00
```
## Building the Docker container
From inside the `docker/` subdirectory, build the image using the following command:
2023-09-13 22:02:43 +00:00
`REGISTRY=<registry url> LATEST=yes TAG=alpine ./build.sh`
