From 63d02d2baf5403daec2ab8cbd38c7a13498c36fd Mon Sep 17 00:00:00 2001 From: ildyria Date: Thu, 2 Jul 2026 16:11:39 +0200 Subject: [PATCH] more docs --- src/content/docs/docs/faq/general.md | 24 ++---- .../docs/docs/features/facial-recognition.md | 45 ++++++++++- src/content/docs/docs/features/flow.md | 78 ++++++++++++++++--- src/content/docs/docs/features/frame.md | 32 ++++++-- src/content/docs/docs/features/rss.md | 26 +++++-- src/content/docs/docs/features/slideshow.md | 29 +++++-- src/content/docs/docs/features/tagging.md | 39 +++++++--- .../docs/docs/getting-started/settings.md | 2 +- src/content/docs/docs/se/statistics.md | 40 ++++++---- src/content/docs/docs/se/user-groups.md | 19 +++-- 10 files changed, 257 insertions(+), 77 deletions(-) diff --git a/src/content/docs/docs/faq/general.md b/src/content/docs/docs/faq/general.md index 86a352e..8065a56 100644 --- a/src/content/docs/docs/faq/general.md +++ b/src/content/docs/docs/faq/general.md @@ -64,7 +64,7 @@ There is a discord associated with the project, feel free to join us there: http ### How can I set thumbnails for my albums? -Thumbnails are selected automatically from the photos inside the album (and any subalbums) based on the photo sorting order specified in the [Settings](/docs/getting-started/settings/#sorting). _Precedence is given to starred photos_. In practical terms, if only one photo inside an album is starred, that photo is guaranteed to be the top thumbnail. +Thumbnails are selected automatically from the photos inside the album (and any subalbums) based on the photo sorting order specified in the [Settings](/docs/getting-started/settings/#sorting_photos_col). _Precedence is given to starred photos_. In practical terms, if only one photo inside an album is starred, that photo is guaranteed to be the top thumbnail. ### Is it possible to create folders inside another folder? If so, how to do that? @@ -77,7 +77,7 @@ Either press `n` (as **N**ew) or use the add menu. In order to bypass the CSRF protection, you can set up the `api_key` setting to a secret value and send that value over in the `Authorization` header. Note that `api_key` only disables the CSRF protection, you still need to authenticate to the server. -In order to authenticate, use [Session::login](https://lycheeorg.dev/docs/api.html#apisessionlogin) and pass the returned `lychee_session` cookie to all subsequent requests. +In order to authenticate, use [Session::login](https://demo.lycheeorg.dev/docs/api) and pass the returned `lychee_session` cookie to all subsequent requests. The related code is available [here](https://github.com/LycheeOrg/Lychee/blob/master/app/Http/Middleware/VerifyCsrfToken.php#L55) @@ -222,15 +222,10 @@ Edit the `custom.js` file in `/path/to/lychee/public/dist/` or use the _"Persona ### How is the upload folder protected? -From [#304](https://github.com/LycheeOrg/Lychee/issues/304) +There are now two possibilities: -Short version: It's not protected - -Long answer: [#295](https://github.com/LycheeOrg/Lychee/pull/295) added some protection through symlinking, so that the URLs used are temporary. - -Right now, the protection is basically through the use of difficult to guess names (it's an MD5 checksum of the system time at the time of upload). [#295](https://github.com/LycheeOrg/Lychee/pull/295) not only made those names temporary (this needs to be enabled in the Settings, BTW) but it also provided optional support for hiding the full-size version (this is only effective with symlinking as without it the URL can be derived from that of intermediate-size images). - -[@ildyria](https://github.com/ildyria) recently posted the following link on how a more effective protection could be implemented: https://bedigit.com/blog/laravel-5-how-to-access-image-uploaded-in-storage-within-view/. He didn't go down that route himself due to performance concerns but we agree that if somebody contributed a clean implementation as an option, we'd probably accept it. +- Use signed URLs to access the photos and avoid hot-linking, via the [`temporary_image_link_enabled`](/docs/getting-started/settings/#temporary_image_link_enabled) setting. +- Use AES encrypted URLs, via the [`secure_image_link_enabled`](/docs/getting-started/settings/#secure_image_link_enabled) setting (only available for SE users). ### My login is timing out after two hours, how can this be changed? @@ -238,7 +233,7 @@ You can edit your `.env` and modify the `SESSION_LIFETIME=120` part (in minutes) ### How can I see the correct client IP address when running Lychee behind Cloudflare? -Please see [https://github.com/monicahq/laravel-cloudflare](https://github.com/monicahq/laravel-cloudflare). The Lychee file that needs changing can be found [here](https://github.com/LycheeOrg/Lychee/blob/master/app/Http/Middleware/TrustProxies.php). +Please see [https://github.com/monicahq/laravel-cloudflare](https://github.com/monicahq/laravel-cloudflare). The Lychee file that needs changing can be found [here](https://github.com/LycheeOrg/Lychee/blob/master/config/trustedproxy.php). ### Can I set up Lychee to watch a folder for new images and automatically add them to albums? @@ -259,10 +254,3 @@ For example: ![](/docs/img/special-right-click-missing.png) No this is normal. This user does not have the ownership of that Album, so the right click is not available. You can see _sharing_ as a _read_ permission. - -### The divider h1 shows the text "Admin" when logged in with an ordinary user. Shouln't this be "Albums"? - -Actually no, this is because the user does not have any albums (yet). The `h1` divider is to show who is the owner of those albums. See below. -![2020-02-19_3840x1080_12:29:19](https://user-images.githubusercontent.com/627094/74830496-92c3a200-5313-11ea-9065-60cb8090c7ac.png) -And yes the right-click menu is available on the _PhD Defenses_ part but not in the _Admin_ parts. -Also because this user has upload right, he can see the _Unsorted, Public, Starred, Recent_ smart albums. diff --git a/src/content/docs/docs/features/facial-recognition.md b/src/content/docs/docs/features/facial-recognition.md index ed6983d..f67c49d 100644 --- a/src/content/docs/docs/features/facial-recognition.md +++ b/src/content/docs/docs/features/facial-recognition.md @@ -24,7 +24,7 @@ Facial recognition processes biometric data, which is subject to strict legal re - **Auto-scan on upload** — newly uploaded photos are automatically queued for face detection once both AI Vision and facial recognition are enabled. - **Detection** — the AI Vision service finds faces in each photo and returns bounding boxes plus an embedding (a numeric "fingerprint") for each face. -- **Clustering** — faces that aren't yet linked to a person are grouped into clusters of similar-looking faces, so you can label a whole group at once instead of one face at a time. +- **Clustering** — faces that aren't yet linked to a person are grouped into clusters of similar-looking faces, so you can label a whole group at once instead of one face at a time. Clustering can be re-run at any time from _Settings ⇒ Maintenance ⇒ Run Clustering_ (visible whenever unclustered faces exist) — useful after changing the microservice's `VISION_FACE_CLUSTER_EPS` if the resulting clusters aren't grouping people as expected. It only affects faces not yet assigned to a person; already-labelled faces are left untouched. - **Overlays** — when viewing a photo, detected faces are shown as overlays. Press `P` to toggle their visibility. ## People and Person Albums @@ -169,3 +169,46 @@ The container exposes interactive API docs at `/docs` and a health check at `/he |---------------------------------------------|----------------------------------------------------------------------------------| | `php artisan lychee:scan-faces` | Enqueue all unscanned photos for face detection. Use `--album={id}` to limit to the direct photos of one album. | | `php artisan lychee:rescan-failed-faces` | Re-enqueue photos whose scan previously failed. Add `--stuck-pending` (with `--older-than=`, default 60) to also reset scans stuck in "pending" back to unscanned. | + +## Troubleshooting + +**Facial recognition options don't appear in Settings:** +- Check that `ai_vision_enabled` and `ai_vision_face_enabled` are both turned on. Facial recognition is disabled by default and requires both. + +**Diagnostics reports the AI Vision service as unreachable:** +- Verify `AI_VISION_FACE_URL` and `AI_VISION_FACE_API_KEY` are set in Lychee's `.env` and match the `VISION_FACE_API_KEY` configured on the microservice side. +- Confirm the microservice container is running and reachable from Lychee (`docker-compose logs` on the facial-recognition service, or check its `/health` endpoint). +- If Lychee and the microservice are on different hosts/networks, make sure firewalls and Docker networks allow the connection. + +**Photos are never scanned / stay stuck on "pending":** +- Confirm a Lychee queue worker is running — face scans are processed asynchronously like other jobs. +- Run `php artisan lychee:rescan-failed-faces --stuck-pending` to reset scans that have been stuck in "pending" for longer than `--older-than` minutes (default 60). +- Check the microservice logs for `429 Too Many Requests`, which means its job queue (`VISION_FACE_QUEUE_MAX_SIZE`) is full; either wait for it to drain or increase the limit. + +**Some faces in a photo are detected but others are missed:** +- Check `VISION_FACE_DETECTION_THRESHOLD` (default `0.5`) on the microservice — faces below this confidence are dropped; lower it to catch more faces at the cost of more false positives. +- Small, angled, or partially occluded faces are the most likely to be missed. `VISION_FACE_MIN_FACE_SIZE_PIXELS` (default `0`, i.e. no filter) can be raising the bar further if set above zero — make sure it isn't filtering out legitimately small faces. +- Blurry faces are discarded via `VISION_FACE_BLUR_THRESHOLD` (default `0.5`, Laplacian variance) — lower it if sharp-enough faces are still being rejected. +- `VISION_FACE_MAX_FACES_PER_PHOTO` (default `10`) caps how many faces are returned per photo; group photos with more people than this will only have the top matches included. +- Try a different `VISION_FACE_DETECTOR_BACKEND` (`retinaface`, `mtcnn`, `opencv`, `ssd`) — detectors vary in recall depending on pose, lighting, and image resolution. + +**Clustering groups unrelated faces together, or fails to group similar faces:** +- Clustering is controlled by `VISION_FACE_CLUSTER_EPS` (default `0.6`), the DBSCAN epsilon (maximum cosine distance) allowed within a cluster. Lower it if dissimilar people are being grouped together; raise it if the same person is being split across multiple clusters. +- To apply a new value: update `VISION_FACE_CLUSTER_EPS` in the microservice's `.env`, restart the microservice so it picks up the change, then re-trigger clustering from _Settings ⇒ Maintenance ⇒ Run Clustering_ in Lychee. This re-clusters every currently unassigned face with the new epsilon — repeat with a different value if the result still isn't right. +- The `VISION_FACE_MODEL_NAME` (default `ArcFace`) recognition model determines embedding quality — a different model may produce more consistent embeddings for your photo set, but changing it does not retroactively update existing embeddings. +- Poor detections (blurry, low-confidence, or partial faces — see above) produce noisy embeddings that cluster poorly; fixing detection quality often improves clustering as a side effect. +- Clusters are only formed from faces not yet linked to a person; once a face is assigned to a person it's removed from the pool of unclustered faces. + +**Faces are detected but nothing shows up when opening a photo:** +- Press `P` to toggle overlay visibility — they may just be hidden. +- Check `ai_vision_face_overlay_enabled` and `ai_vision_face_overlay_default_visibility`. +- Overlays and the People page are gated by `ai_vision_face_permission_mode` — see [Permission modes](#permission-modes); as an ordinary user you may simply lack the rights to view them. + +**Selfie claim doesn't match the right person:** +- The match confidence must exceed `ai_vision_face_selfie_confidence_threshold` (default `0.8`). Lower it if legitimate matches are being rejected, or raise it if false positives occur. +- Make sure the person you expect to match has enough labelled faces for a reliable embedding average. + +**The microservice fails to start:** +- Missing required environment variables (`VISION_FACE_LYCHEE_API_URL`, `VISION_FACE_API_KEY`) produce a formatted error at startup — check the container logs for which variable is missing. +- If using self-signed certificates for the Lychee callback URL, set `VISION_FACE_VERIFY_SSL=false`. +- For local development without a reachable Lychee instance, set `VISION_FACE_SKIP_LYCHEE_CHECK=true`. diff --git a/src/content/docs/docs/features/flow.md b/src/content/docs/docs/features/flow.md index 615f3ae..179555a 100644 --- a/src/content/docs/docs/features/flow.md +++ b/src/content/docs/docs/features/flow.md @@ -5,18 +5,78 @@ sidebar: order: 6 --- -Flow displays albums in a feed-like manner, similar to social media platforms. It provides a scrollable, visually engaging way to browse your photo library. +Flow displays albums in a feed-like manner, similar to social media platforms. Each album becomes a scrollable card — with a cover image, a carousel of the photos inside, and metadata such as its date range — giving you a visually engaging alternative to browsing the album tree. -## Features +## How it works -- **Standalone page** — access Flow as a dedicated page -- **Access control** — respects album-level permissions -- **Configurable base album** — choose which album tree feeds the Flow +- Flow starts from a base album (the gallery root by default, or a specific album set via `flow_base`) and turns eligible **descendants** of that base into cards — the base album itself is never shown as a card. +- By default (`flow_include_sub_albums` off), only the **direct children** of the base are considered — nested sub-albums further down the tree are not included. Enabling `flow_include_sub_albums` includes every descendant at any depth; if no base album is set either, this effectively means every album in the gallery is a candidate. +- Only albums that directly contain photos become cards. Enabling `flow_include_photos_from_children` also includes albums with no photos of their own by showing photos from their descendants instead — **not recommended**, since it can be slow and memory-intensive on large trees. +- Album descriptions are rendered as Markdown on the card. +- The owner's name is only shown to logged-in viewers; anonymous visitors (when `flow_public` is enabled) never see it. +- Cards are loaded a page at a time as you scroll, rather than all at once. +- Flow is exposed as its own standalone page and respects the same album-level permissions as the rest of the gallery — a user only sees cards for albums they're allowed to access. + +### Ordering and the `opt-in` strategy + +`flow_strategy` controls both which albums are eligible and how the feed is sorted: + +- `auto` (default) — every eligible album is included, newest-created first. +- `opt-in` — only albums that have been explicitly published to the feed are included, sorted by their publish date (newest first). + +:::note +`opt-in` relies on each album having a publish timestamp, but at the time of writing there is no interface action exposed to set this per album. Until one ships, switching `flow_strategy` to `opt-in` will result in an empty Flow feed — stick with `auto` (the default) for a usable feed today. +::: + +### Sensitive (NSFW) albums in Flow + +Albums marked as sensitive are handled the same way as elsewhere in Lychee, via the [Sensitive Albums settings](/docs/getting-started/settings/#sensitive-albums): + +- `hide_nsfw_in_flow` (default: on) — excludes sensitive albums from Flow entirely. +- `flow_blur_nsfw_enabled` (default: on) — if sensitive albums aren't hidden, blur their photos on the card until a user clicks through. + +## Settings + +The feature is controlled by a `Flow` category of [Settings](/docs/getting-started/settings/): + +| Setting | Description | Default | +|------------------------------------------|-----------------------------------------------------------------------------------------------------|-------------------| +| `flow_enabled` | Master toggle for the Flow view. | on | +| `flow_public` | Allow anonymous (non-logged-in) users to access Flow. | off | +| `flow_base` | Album ID used as the root of the feed. Leave empty to use the gallery root. | empty | +| `flow_max_items` | Number of albums loaded per Flow page. Lower means more requests; higher means more memory usage. | `10` | +| `flow_strategy` SE | See [Ordering and the opt-in strategy](#ordering-and-the-opt-in-strategy). | `auto` | +| `flow_include_sub_albums` SE | Include all descendants of the base album, not just its direct children. | off | +| `flow_include_photos_from_children` SE | Show photos from child albums when an album itself has none. **Not recommended** — can cause memory exhaustion and slowdowns on large trees. | off | +| `flow_open_album_on_click` SE | Navigate to the album when a card is clicked, instead of opening the photo viewer directly. | off | +| `flow_display_open_album_button` SE | Show an explicit "Open Album" button on each card. | off | +| `flow_image_header_enabled` SE | Show an image header at the top of each card, featuring the album cover. | on | +| `flow_image_header_cover` SE | How the header image fills the card: `cover` crops to fill, `fit` scales to fit. | `cover` | +| `flow_image_header_height` SE | Height of the image header, in `rem`. | `24` | +| `flow_carousel_enabled` SE | Show a photo carousel below the image header on each card. | on | +| `flow_carousel_height` SE | Height of the photo carousel, in `rem`. | `6` | +| `flow_highlight_first_picture` SE | Use the album's first photo as the main image instead of its cover photo. | on | +| `flow_min_max_enabled` SE | Show the min/max date range of the album's photos on each card. | on | +| `flow_min_max_order` | Which date (older or newer) is shown first in the min/max date range. | `older_younger` | +| `flow_display_statistics` SE | Show view, share, and download counts on each card. Also requires the [`metrics_enabled`](/docs/getting-started/settings/#metrics_enabled) master toggle and read-metrics permission on the album. | on | +| `flow_compact_mode_enabled` SE | Clamp the description to 3 lines and hide extra details (photo/child counts); a "Show more" button expands the card. | on | + +`flow_base`, `flow_max_items`, and `flow_min_max_order` are available on the free edition; the rest of the card's layout and the inclusion strategy require the [Supporter Edition](/docs/se/overview/). + +### Date format + +Two settings accept [PHP date format strings](https://www.php.net/manual/en/datetime.format.php) and require the Supporter Edition: + +| Key | Default | Used for | +|----------------------------------|------------------------------|----------------------------------------| +| `date_format_flow_published` | `M j, Y, g:i:s A e` | Album published/created date shown on cards | +| `date_format_flow_min_max` | `F Y` | Min/max date range shown on cards | ## Supporter Edition Features -With the [Supporter Edition](/docs/se/overview/): +With the [Supporter Edition](/docs/se/overview/) you get finer control over the feed: -- **Compact mode** — display flow cards in a more compact layout -- **Extensive customizations** — fine-tune the appearance of flow cards -- **Custom strategy** — choose between opt-in and automatic inclusion of albums (coming soon) +- **Opt-in strategy** — switch `flow_strategy` from `auto` (every eligible album) to `opt-in` (only explicitly published albums); see the [caveat above](#ordering-and-the-opt-in-strategy) about its current front-end support. +- **Nested album inclusion** — pull in every descendant of the base album, not just its direct children, via `flow_include_sub_albums`. +- **Compact mode** — clamp cards to a shorter, summarized layout via `flow_compact_mode_enabled`. +- **Extensive card customization** — toggle the image header, carousel, statistics, and min/max date range independently, and tune their sizing. diff --git a/src/content/docs/docs/features/frame.md b/src/content/docs/docs/features/frame.md index a5455c1..4a82f58 100644 --- a/src/content/docs/docs/features/frame.md +++ b/src/content/docs/docs/features/frame.md @@ -5,14 +5,34 @@ sidebar: order: 8 --- -The Frame module turns Lychee into a digital photo frame, cycling through your photos in a fullscreen display. +Frame turns Lychee into a digital photo frame: opening `/frame` goes fullscreen and cycles through random photos one at a time, each shown centered over a blurred, full-bleed copy of itself. -## Features +## How it works -- Fullscreen photo display mode -- Automatic photo rotation -- Configurable display interval -- Works with any album or the entire library +- Each cycle picks a random photo — from a specific album if `random_album_id` is configured, or otherwise from every photo you're allowed to search across the whole gallery. +- Videos are skipped: if a random pick turns out to be a video, Frame retries (up to 5 times) before giving up for that cycle. +- Sensitive (NSFW) photos are excluded automatically when `hide_nsfw_in_frame` — a [Sensitive Albums setting](/docs/getting-started/settings/#sensitive-albums) — is enabled. +- Press `Esc`, or use the on-screen back button, to exit fullscreen and return to wherever you started Frame from. + +## Accessing Frame + +- Frame is reached at `/frame`, or via its entry in the left menu. +- The menu entry is only shown when `mod_frame_enabled` is on **and** the current user can access the album configured by `random_album_id`. If that album is private and the viewer isn't logged in (or lacks the rights), the menu entry disappears for them — even though the route itself would still work for someone who does have access. +- By default, `random_album_id` points at the built-in [Highlighted smart album](/docs/features/smart-albums/) (your starred photos). Set it to any album ID to restrict Frame to that album, or clear it to draw from every searchable photo in the gallery. + +## Settings + +| Setting | Description | Default | +|------------------------|---------------------------------------------------------------------------------|-----------------| +| `mod_frame_enabled` | Master toggle for Frame mode. | on | +| `random_album_id` | Album ID used as the photo source. Leave empty to draw from all searchable photos. | `highlighted` | +| `mod_frame_refresh` | Seconds between photo changes. | `30` | + +`hide_nsfw_in_frame`, under [Sensitive Albums](/docs/getting-started/settings/#sensitive-albums), additionally controls whether sensitive photos can appear in the rotation. + +## Building a custom frame client + +Besides the built-in fullscreen view, Lychee also exposes a `Photo::random` endpoint (see the [API reference](/docs/administration/api/)) that returns a full photo resource — not just an image URL — using the same random-selection logic (album source, video skipping, NSFW exclusion) as the built-in Frame. This is meant for driving your own external photo-frame client, for example on a Raspberry Pi or another dedicated display, when you need more than a bare image URL. ## Use Cases diff --git a/src/content/docs/docs/features/rss.md b/src/content/docs/docs/features/rss.md index 5a211dd..13f4ae0 100644 --- a/src/content/docs/docs/features/rss.md +++ b/src/content/docs/docs/features/rss.md @@ -5,10 +5,26 @@ sidebar: order: 9 --- -Lychee can generate RSS feeds for your photo library, allowing users to subscribe and receive updates when new photos are added. +Lychee can publish a feed of your most recently added photos, so RSS readers can notify subscribers as your library grows. -## Features +## How it works -- RSS feed generation for public albums -- Compatible with standard RSS readers -- Automatic updates when new photos are published +- The feed lists photos added within the last `rss_recent_days` days (default: `7`), newest first, capped at `rss_max_items` entries (default: `100`). +- It reflects whatever's searchable to whoever requests it — the same visibility rules as [Search](/docs/features/search/). Since RSS readers don't carry your Lychee login session, in practice this means the feed only ever shows publicly accessible photos. +- Each entry links to the photo in the gallery, and its enclosure is the **original, full-resolution** file — not a thumbnail — so keep bandwidth in mind if `rss_max_items` is set high. +- Descriptions are rendered as Markdown; the author is the photo owner's display name (or username if none is set); the category is the containing album's title. +- Sensitive (NSFW) photos are excluded when `hide_nsfw_in_rss` — a [Sensitive Albums setting](/docs/getting-started/settings/#sensitive-albums) — is enabled. + +## Accessing the feed + +Despite the setting being named `rss_enable`, the feed is actually served at **`/feed`**, not `/rss` — subscribe to `https://your-lychee-instance/feed`. Requesting it while `rss_enable` is off returns an error rather than an empty feed. + +## Settings + +| Setting | Description | Default | +|----------------------|-----------------------------------------------------------|-----------| +| `rss_enable` | Master toggle for the feed at `/feed`. | off | +| `rss_max_items` | Maximum number of items in the feed. | `100` | +| `rss_recent_days` | Only include photos uploaded within the last X days. | `7` | + +`hide_nsfw_in_rss`, under [Sensitive Albums](/docs/getting-started/settings/#sensitive-albums), additionally excludes sensitive photos from the feed. diff --git a/src/content/docs/docs/features/slideshow.md b/src/content/docs/docs/features/slideshow.md index c4777e1..c065741 100644 --- a/src/content/docs/docs/features/slideshow.md +++ b/src/content/docs/docs/features/slideshow.md @@ -5,12 +5,27 @@ sidebar: order: 7 --- -Lychee includes a built-in slideshow mode for viewing photos in fullscreen with automatic transitions. +Lychee includes a built-in slideshow mode that auto-advances through a set of photos, with a brief fade-to-black transition between each one. -## Features +## How it works -- Fullscreen photo display -- Previous and next navigation -- Auto-advance with configurable timing -- Works within albums and across the library -- Keyboard navigation support (see [Keyboard Shortcuts](/docs/usage/keyboard/)) +- Photos advance automatically every `slideshow_timeout` seconds (default: `5`). +- Reaching the last photo loops back to the first (and vice versa) if `photos_wraparound` is enabled — otherwise the slideshow simply stops there. +- Videos are not skipped: the slideshow waits for a video to finish playing before advancing, rather than switching after the usual timeout. + :::caution + This wait relies on the video actually starting to play. If `autoplay_enabled` is turned off, a video reached during a slideshow will never autoplay and therefore never fire its "ended" event — the slideshow will appear to hang on that video until you manually skip past it. + ::: +- You can still navigate manually with the left/right arrow keys (see [Keyboard Shortcuts](/docs/usage/keyboard/)) while a slideshow is running; doing so shows that photo immediately and restarts the auto-advance timer from there. + +## Starting a slideshow + +A "Play" button starts the slideshow wherever you're viewing a set of photos: from an album's header, from within the photo viewer's toolbar, or from Tag results, Search results, the Timeline, or a Person's photos. The toolbar and other UI chrome automatically fade out once the slideshow is running (reappearing on hover on larger screens) to keep the view uncluttered; opening the toolbar and pressing the button again stops the slideshow. + +## Settings + +| Setting | Description | Default | +|--------------------------|-----------------------------------------------------------------------------------|-----------| +| `slideshow_enabled` | Master toggle for the slideshow "Play" button. | on | +| `slideshow_timeout` | Seconds between photos while a slideshow is running. | `5` | +| `photos_wraparound` | Loop back to the first photo after the last one (and vice versa). | on | +| `autoplay_enabled` | Set the `autoplay` attribute on video elements — see the caution above; disabling it can stall slideshows on video photos. | on | diff --git a/src/content/docs/docs/features/tagging.md b/src/content/docs/docs/features/tagging.md index 0dd63f1..263c3a8 100644 --- a/src/content/docs/docs/features/tagging.md +++ b/src/content/docs/docs/features/tagging.md @@ -7,22 +7,43 @@ sidebar: Tags provide a flexible way to categorize and find photos across your entire library. +:::note +Tags are shared, global entities — if two users both tag a photo `car`, they're using the same underlying tag. Management actions (rename, merge, delete) only ever touch **your own** photos; other users' photos keep the tag untouched, unless you're an admin, in which case they apply gallery-wide. A tag is only fully removed once no photo anywhere references it anymore. +::: + ## Tag Management -- **Rename tags** — update tag names across all associated photos -- **Merge tags** — combine multiple tags into one -- **Delete tags** — remove tags from the system -- **Tag management view** — manage all tags from a single interface +Any user with upload rights (not just admins) can manage tags from the Tag Management view: + +- **Rename tags** — internally this finds (or creates) a tag with the new name and migrates your photos to it, then removes the old name from your photos. If another user still has photos under the old name, their tag is left alone. +- **Merge tags** — combine one tag into another; your photos (and any of your [Tag Albums](#tag-albums)) referencing the source tag are moved to the destination tag. +- **Delete tags** — remove a tag from your own photos. The tag itself disappears once no one's photos reference it anymore. +- **Tag management view** — lists every tag with a photo count. As a non-admin, the count and the tag's photo listing only ever reflect **your own** photos, even though the tag name may be shared with other users. ## Using Tags -- **Photo listing per tag** — view all photos with a specific tag -- **Auto-completion** — get tag suggestions while typing -- **Smart Albums by tag** — create dynamic albums based on tag selections -- **Bulk tagging** — apply tags to multiple photos at once +- **Tag descriptions** — besides a name, a tag can also have a description. +- **Photo listing per tag** — view all of your own photos under a specific tag (admins see everyone's). +- **Auto-completion** — the tag input suggests existing tags (with their photo counts) as you type. When tagging a photo, you can also add a brand-new tag by typing a name that doesn't exist yet; when picking tags to build a Tag Album, only existing tags are offered. +- **Bulk tagging** — apply tags to multiple selected photos at once, either adding them alongside existing tags or overriding (replacing) whatever tags those photos already had. + +## Tag Albums + +Tag Albums are dynamic, tag-driven smart albums: pick one or more tags and a match mode, and every photo carrying **any** of them (OR) or **all** of them (AND) is included automatically — no manual sorting required. Like other smart albums, they re-evaluate live: tag or re-tag a photo and matching Tag Albums update immediately. See [Smart Albums](/docs/features/smart-albums/#user-created-smart-albums) for how they compare to the built-in smart albums, and the `TA_override_visibility` setting below for making their contents visible independently of each photo's own visibility. + +## Settings + +| Setting | Description | Default | +|-----------------------------------|-----------------------------------------------------------------------------------------------------|-----------| +| `TA_override_visibility` | Tag Album visibility overrides individual photo visibility, making matching photos publicly accessible regardless of their own settings. | off | +| `hide_nsfw_in_tag_albums` | Hide sensitive photos from Tag Albums. | on | +| `hide_nsfw_in_tag_listing` | Hide sensitive photos from the per-tag photo listing. | on | +| `photo_thumb_tags_enabled` SE | Show tags on photo thumbnails in the album view. Has no effect when `photo_thumb_info` is set to `description`. | off | + +The NSFW-related settings live under [Sensitive Albums](/docs/getting-started/settings/#sensitive-albums); `TA_override_visibility` and `photo_thumb_tags_enabled` live under [Smart & Featured Albums](/docs/getting-started/settings/#smart--featured-albums) and [Gallery](/docs/getting-started/settings/#gallery) respectively. ## Supporter Edition Features With the [Supporter Edition](/docs/se/overview/): -- **Display tags on album view** — show tags directly in the album grid +- **Display tags on album view** — show tags directly on photo thumbnails in the album grid, via `photo_thumb_tags_enabled`. diff --git a/src/content/docs/docs/getting-started/settings.md b/src/content/docs/docs/getting-started/settings.md index e71f133..fe75201 100644 --- a/src/content/docs/docs/getting-started/settings.md +++ b/src/content/docs/docs/getting-started/settings.md @@ -1103,7 +1103,7 @@ Show GPS coordinates to anonymous users. #### `rss_enable` _(boolean; default: `0`)_ -Enable the RSS feed at `/rss`. +Enable the RSS feed at `/feed`. #### `rss_max_items` _(positive integer; default: `100`)_ diff --git a/src/content/docs/docs/se/statistics.md b/src/content/docs/docs/se/statistics.md index 723ce9b..82d5960 100644 --- a/src/content/docs/docs/se/statistics.md +++ b/src/content/docs/docs/se/statistics.md @@ -8,28 +8,38 @@ sidebar: variant: tip --- -The Statistics module provides insights into your Lychee installation and photo library. +Lychee SE bundles two distinct subsystems here: **usage statistics** about your library's storage and growth, and **engagement metrics** tracking how photos and albums are viewed, downloaded, and shared. -## Installation Statistics +## Usage Statistics -View statistics about your Lychee instance, including storage usage, number of photos, albums, and users. +Accessible from the dedicated Statistics page: -## Album Statistics +- **Storage breakdown** — total space used, broken down per size-variant type (thumbnail, small, medium, original, etc.) and per user. +- **Activity over time** — a calendar-style chart of photo counts, by upload date or by the photo's original taken-at date. +- **Per-album breakdown** — a table of storage usage and photo counts per album, both for the album's own photos and including all descendants, collapsible into per-user totals. +- Regular users only see statistics for their own photos and albums; admins see the whole instance. -Per-album statistics show: +## Engagement Metrics -- Number of photos per album -- Storage usage per album -- Download and share counts +Enable `metrics_enabled` to start recording view, download, and share counts on photos and albums: -## Photo Statistics +- Counts appear as small badges on albums and photos, and on [Flow](/docs/features/flow/) cards. +- Anonymous visitors are always counted when enabled; logged-in users are only counted if `metrics_logged_in_users_enabed` is also on. **Admin activity is never counted**, so browsing as an admin won't inflate your own stats. +- Who can see these counts is controlled separately by `metrics_access` (admin, owner, logged-in users, or public). -Track individual photo metrics: +### Live Metrics -- Download counts -- Share statistics -- View counts +`live_metrics_enabled` additionally turns on a real-time activity feed — a running log of visits, favourites, downloads, and shares as they happen. Photo-level page visits are deliberately excluded from this feed to keep it readable; only album-level visits and the other actions are listed. As with the counts above, non-admins only ever see activity for their own albums and photos. Entries older than `live_metrics_max_time` days are purged automatically the next time the feed is loaded — there's no separate scheduled cleanup job. Access to the feed itself is controlled by `live_metrics_access` (admin or logged-in users). -## Color Palette Extraction +## Settings -Lychee SE can extract the dominant color palette from your photos, useful for visual organization and search. +The [`Pro`](/docs/getting-started/settings/#pro) settings category controls engagement metrics: + +| Setting | Description | Default | +|----------------------------------------|-----------------------------------------------------------------------------|-----------| +| `metrics_enabled` | Master toggle for view/download/share counts on photos and albums. | off | +| `metrics_logged_in_users_enabed` | Also count logged-in users (admins are always excluded). | off | +| `metrics_access` | Who can see the counts: `admin`, `owner`, `logged-in users`, or `public`. | `admin` | +| `live_metrics_enabled` | Turn on the live activity feed. | off | +| `live_metrics_access` | Who can view the live feed: `admin` or `logged-in users`. | `admin` | +| `live_metrics_max_time` | How many days of live activity to retain. | `30` | diff --git a/src/content/docs/docs/se/user-groups.md b/src/content/docs/docs/se/user-groups.md index 4f2ddd4..debf3d6 100644 --- a/src/content/docs/docs/se/user-groups.md +++ b/src/content/docs/docs/se/user-groups.md @@ -8,13 +8,20 @@ sidebar: variant: tip --- -User Groups allow you to organize users and manage permissions collectively rather than individually. +User Groups let you share albums with a whole set of users at once, and update their access collectively, instead of sharing with — and maintaining — each user individually. -## Features +## How it works -- **Group administration** — delegate group management to group admins -- **Group sharing** — share albums with entire groups instead of individual users -- **Per-album access control** — set access rights for groups on specific albums +- A group has a name, an optional description, and a member list. Every member holds one of two roles: `member` or `admin`. +- Only a Lychee administrator can create or delete a group itself. +- Group **admins** can rename the group, edit its description, and add, remove, or re-role its members — without needing full Lychee admin rights. This is the delegation the "Group administration" feature refers to. +- A group's member list is only visible to Lychee admins and to that group's own members; other users can't see who belongs to a group they aren't in. + +## Sharing with groups + +- When sharing an album, you can pick a group the same way you'd pick an individual user — the share-target search lists both users and groups together, with a distinct icon for groups. +- A group share grants exactly the same set of permissions as an individual [user share](/docs/usage/sharing/): full-photo access, download, upload, edit, and delete, configured per group per album. +- Every member of the group inherits the album's access through the group; there's no way to override the grant for a single member within that group's share. ## Use Cases @@ -24,4 +31,4 @@ User Groups allow you to organize users and manage permissions collectively rath ## Creating Groups -Groups can be created and managed from the admin panel. Assign users to groups and configure album access per group. +Groups themselves are created and deleted from the admin panel by a Lychee administrator. From there, membership and group details can either stay with the admin or be handed off to a group admin, who can manage members without needing broader Lychee admin rights.