Skip to content

2. User Guide

Jump to bottom
DannyVFilms edited this page Jul 31, 2026 · 7 revisions

Using Floppy (Overview)

Floppy is built around a simple loop: track items as you watch, read, or play them, and Floppy turns that activity into History and Statistics. Imports and webhooks can automate most of this, while Preferences and Collection let you shape how everything is displayed.

The mental model

Track items -> generates History

  • You add items by searching, importing, or creating custom entries.
  • Tracking progress (plays, episodes, pages, status changes) creates History entries.
  • Status values include Planning, In progress, Completed, Paused, and Dropped.
  • Integrations (Plex, Trakt, Pocket Casts, Last.fm, etc.) can add plays and updates automatically.

History and Statistics are cached

  • History and Statistics are cached for speed, especially on large libraries.
  • When a cache is stale, the UI shows a "Refreshing ... in background" banner and updates when ready.
  • Cache refreshes run in the background via Redis + Celery.
  • Some filtered views may bypass caches and compute on demand.

Collection is a metadata layer

  • Collection tracks physical or format metadata (resolution, HDR, audio, bitrate, etc.).
  • It is separate from tracking status and progress.
  • Metadata can be added manually or populated from integrations (Plex, Jellyfin, Emby).
  • Collection data can drive filters and display badges in list and detail views.

Core pages

Search and Add

Floppy's search lives in the top bar and is the fastest way to add items. It respects your enabled media types, supports multiple sources per type, and includes a barcode scan flow for books.

Search dropdown and enabled media types

  • The media type dropdown is populated from your enabled media types (Settings -> Sidebar; see Preferences for related settings).
  • Disabled types are removed from the dropdown (and from the sidebar, calendar, and notifications).
  • Your last used search type is remembered; if you are on a TV Season page it defaults to TV.

Search sources and results

  • Search results show a Source picker (e.g., TMDB, MAL, IGDB, OpenLibrary, MusicBrainz) based on the current media type.
  • You can toggle between grid and list layouts on the results page.
  • Music searches return separate sections for Artists, Albums, and Tracks.
    • Clicking an Artist or Album result creates it and takes you to its detail page.

Adding items and tracking basics

  • Click a poster/card to open the item detail page (see Media Details and Tracking).
  • Use the track/edit button on a result card to add it to your tracker.
    • You can set status (Planning, In progress, Completed, Paused, Dropped), score, and progress.
  • Use the Lists button to add items to custom lists (see Lists).
  • For manual entries, use "Create Custom" from the sidebar.
  • Integrations and imports can add and update items automatically (see Import Overview).

Book barcode scanning (ZXing + image upload)

  • When the search type is Book, a camera icon appears in the search field.
  • Clicking the icon lets you upload a photo; Floppy uses ZXing to decode the barcode.
  • If a valid ISBN is found, it is inserted into the search box and the search runs automatically.
  • If decoding fails, a toast explains the error and you can retry or type the ISBN manually.

Tips for better scans:

  • Use a clear, well-lit photo with the full barcode visible.
  • Crop tightly to the barcode if possible.
  • If a scan fails, try entering the ISBN directly.

Common errors and expected behavior

  • "No results found": try another source, a different keyword, or a broader search.
  • Media type missing from dropdown: re-enable it in Settings -> Sidebar.
  • Search results look outdated: clear the search cache in Settings -> Advanced (cache expires after ~24 hours).
  • Barcode scan error: refresh the page to reload ZXing, use a clearer image, or enter the ISBN manually.

See also

Home and Media Lists

This page explains how the Home view and per‑media list pages behave: sorting, direction toggles, filters, and special handling for music and podcasts. For layout and display settings, see Preferences.

Home sorting The Home page shows your In Progress items (and Planned items if enabled in Preferences).

Sort options (stored per user):

  • Upcoming
  • Recent
  • Completion
  • Episodes Left
  • Title

The Home sort is saved to your profile and reused on the next visit.

Media list sorting + direction toggles Each media type has its own saved sorting preferences:

  • Sort field (Rating, Title, Progress, Start Date, End Date, Time Left)
  • Sort direction (ascending/descending)
  • Layout (grid/table)
  • Status filter (All / Completed / In Progress / Planning / Paused / Dropped)

How direction toggles work:

  • Selecting a sort you’re already on toggles asc ⇄ desc.
  • New sorts pick a default direction (Title/Start Date/Time Left default to asc; Rating/Progress/End Date default to desc).

The list page remembers your choices per media type (TV, Movies, Games, etc.).

Time‑left sort (TV only) Time‑left sorting is available only on TV lists. It:

  • Calculates episodes left and total time remaining (using per‑episode runtimes when available).
  • Sorts active shows by least time left first.
  • Groups in‑progress caught‑up shows, completed shows, and dropped shows after active items.

The list UI shows “Episodes Left” and “Time Left” columns when this sort is active.

Filters (status, rating, collection, tags) List pages support:

  • Status filter (All / Completed / In Progress / Planning / Paused / Dropped).
  • Rating filter (Rated / Not Rated).
  • Collection filter (Collected / Not Collected).
  • Tag filter (include or exclude a specific tag).
  • Search within your list.

Collection filter notes:

  • For TV/Anime, a show counts as collected if any episode is collected.
  • Collection filtering applies to standard item lists; tracker‑based lists (music/podcasts) do not use collection state.

Custom tags Tags are personal labels you create to organize items across your library:

  • Open the Tags modal from any media card or detail page to create tags and toggle them on or off for that item.
  • Tag names are user‑scoped (not shared with other users) and case‑insensitive.
  • Filter any list page to items that have a specific tag, or exclude items with a tag, using the tag filter control.
  • A single item can carry multiple tags; tags work across all media types.

Music and Podcast list behavior Music and Podcast list pages show trackers, not individual items:

  • Music list shows tracked Artists (not individual tracks).
  • Podcast list shows tracked Shows (not individual episodes).

Sorting still works (Title, Rating, Start Date), but some item‑level filters (like collection) are not applicable.

See also

Media Details and Tracking

The media detail page is the control center for an item: it shows provider metadata, your tracking status, and your activity history. Most media types share the same structure, with extra behaviors for music and podcasts.

What you can do on detail pages

  • Add an item to your tracker/library from the primary button at the top.
  • Edit status, progress, score, start/end dates, and notes through the track modal.
  • Review the Your History panel for progress or last played, and expand past repeats or sessions.
  • Use Actions to add items to custom lists, open a filtered History view, or sync metadata.
  • Browse related items when the source provides them.

Episode and track interactions

  • TV/Anime/Seasons: episode rows include Track, Lists, and History buttons; last watched and collection info appear under the episode.
  • Music albums: each track has its own track modal, history info, and optional list/history buttons once tracked.
  • Podcasts: episode lists support tracking plays per episode and include a "Mark All Played" action when unplayed episodes exist.

Collection metadata and fetching state

  • The Collection panel appears on detail pages for non-podcast items (public views hide it).
  • TV/Anime shows and seasons display collected season/episode counts, while episodes can show collected resolution.
  • Items show available metadata such as resolution, HDR, audio codec/channels, bitrate, and collected date.
  • If collection data is missing and Plex is connected, the page triggers a background fetch and shows a "Fetching collection data in background..." banner. The page auto-refreshes when data arrives.

Music and podcast detail behavior

  • Music: artist pages link to album detail pages; album pages link back to artists. Artist/album pages show history summaries and provide history links filtered to that artist or album.
  • Podcast: show detail pages track at the show level, with per-episode play tracking underneath. History links open a filtered view for the show while episode modals show per-episode plays.

See also

History

History is the timeline of your activity across media types. It pulls in manual tracking, imports, and webhook plays, then groups everything by day for fast browsing.

What gets logged

  • TV: each completed episode (episodes with an end date).
  • Movies: each play creates a History entry; repeat plays show a play count on the card.
  • Music: track plays (manual or scrobbled) are recorded and grouped by album/day.
  • Podcasts: episode plays are logged from history records and grouped under their show.
  • Games + board games: entries reflect your logging style (sessions or repeats).

History respects your enabled media types (Settings -> Sidebar). If a type is disabled, it is hidden here too.

Filters and navigation The History page does not have its own filter UI. Instead, it opens filtered views when you arrive from other pages (via History buttons/links).

Common entry points to filtered history:

  • Media details pages (TV/Season/Movie/Music/Podcast/Game/Board Game) -> "History" or "Activity History" links.
  • Media cards (grid/list cards include a History button).
  • Statistics cards (e.g., genre cards and other “view history” links).
  • Music artist/album detail pages (History button; see Media Details and Tracking).

Once filtered, History switches to a paginated day list instead of the default month view.

The History page still supports both a fast month view and filtered views:

  • Month view (default): when no filters are active, History shows one month at a time with previous/next navigation.
  • Filtered views: when filters are applied, History switches to paginated day lists.

Filters are usually applied by clicking History buttons in the UI (detail pages, cards, or stats). Supported filters include:

  • Media type (movie, tv, music, podcast, game, board game)
  • Specific items (media_id + source)
  • TV season (season_number)
  • Music artist or album
  • Podcast show
  • Genre
  • Date range (start-date, end-date)
  • Logging style override for games (logging_style=sessions|repeats)

There is also a Release view (history_mode=release) used for anniversary-style browsing (e.g., from Statistics).

Caching behavior History is cached for speed:

  • Unfiltered activity view uses per-day caches and a month index.
  • If the cache is rebuilding, a "Refreshing history in background..." banner appears.
  • The page polls cache status; when refresh completes it automatically reloads to show fresh data.
  • Filtered views bypass the cache and compute on demand, so they skip the refresh banner.

Game logging styles (sessions vs repeats) You can choose a default game logging style in Preferences:

  • Sessions: one entry per play session with a date range and total time/plays.
  • Repeats: spreads total time/plays across each day between start and end dates.

You can also override the style for a specific History view using logging_style=sessions or logging_style=repeats.

See also

Statistics

The Statistics page is a high-level view of your media activity. It aggregates plays and progress across your library, then groups the results into charts and top lists. It is cache-backed for speed.

Range picker (predefined + custom + all time) The range picker drives every card and chart on the page.

Predefined ranges include:

  • Today / Yesterday
  • This Week / Last 7 Days
  • This Month / Last 30 Days / Last 90 Days
  • This Year / Last 6 Months / Last 12 Months
  • All Time

Custom ranges:

  • Use the Custom tab to set explicit start/end dates.
  • Custom ranges compute on demand (they are not stored as long-lived cached pages).

Default range:

  • The page defaults to your Statistics default range preference (see Preferences).

Refresh button + cache banners

  • The refresh button forces a rebuild of the current range.
  • While rebuilding, the page shows a banner:
    • "Refreshing statistics in background..."
    • or "Updating metadata in background..." (when a metadata refresh is running)
  • When the refresh completes, the page auto-reloads to show new data.

Comparison mode A comparison selector on the Statistics page lets you benchmark the current period against a prior one:

  • Previous Period — compares against the immediately preceding period of the same length.
  • Last Year — year-over-year comparison.
  • No Comparison — disables comparisons.

When a comparison is active, each media-type hours card shows:

  • A badge indicating the direction and magnitude of change (e.g., "Up 50%").
  • A tooltip with the current period label and hours, the comparison period label and hours, and the comparison date range.

Labels update automatically to match the selected range (e.g., "This Year / Last Year" for a year-to-date range).

What's in Statistics (high-level) You’ll see a mix of overview cards, distributions, and media-specific sections. The exact cards shown depend on what you’ve tracked in the selected range.

Highlights and activity:

  • First/last play callouts and “Today in History” highlights.
  • Activity History visualization (heatmap/stacked view based on Preferences).
  • Played hours by media type plus summary cards.

Distributions:

  • Media type distribution.
  • Status distribution (overall and by media type).
  • Score distribution by media type.

Top lists:

  • Top played and top rated media.
  • Per-media top sections (e.g., most played, top genres, top albums/artists/tracks).

Per‑media sections:

  • TV, Movies, Games, Music, Podcasts: full activity breakdowns and top lists.
  • Anime and Board Games: appear in top-played sections and hours-by-media cards when present.

Why Statistics may differ from raw History Statistics are aggregated and cached, so they can look different from a raw History timeline:

  • Aggregation: repeated plays are counted and grouped (e.g., music by album/day, podcasts by show/episode).
  • Game logging style: “sessions” vs “repeats” changes how game activity is spread across days.
  • Runtime estimation: some totals rely on stored runtime metadata or progress values.
  • Caching: predefined ranges use cached data; new activity may appear after the next refresh.

See also

Preferences

Preferences control display formats, history behavior, and a few home‑page and mobile UX options. Most settings live in Settings → Preferences. A few UI controls (like the touch hover overlay) live in Settings → Sidebar.

Date & time format Choose how dates and times display across the app:

  • Date format options include system locale, ISO‑8601, and several common month/day/year styles.
  • Time format options include 12‑hour and 24‑hour variants.

Game logging style (History) Controls how game and board‑game activity appears in History:

  • Sessions: one entry per play session (exact history).
  • Repeats: spreads total time/plays across the date range. See History for how these views render.

Statistics default range There isn’t a separate toggle here. Your default range updates automatically whenever you pick a predefined range on the Statistics page (e.g., “Last 12 Months”, “All Time”). See Statistics for range picker behavior.

Mobile layout + quick season update

  • Mobile Grid Layout: compact (3 columns) vs comfortable (2 columns).
  • Quick Season Updates: shows a fast update button on mobile home screens. Recommended for the comfortable grid layout.

Media card subtitle behavior + touch hover overlay

  • Media Card Subtitle: “On hover” or “Always visible” (year/progress subtitles).
  • Hide hover overlay on touch devices: in Settings → Sidebar. This hides the hover action overlay on touch devices for a cleaner mobile experience.

Auto‑pause rules (stale in‑progress) Under Automation → Library Management you can add rules that automatically move stale “In Progress” items to Paused:

  • Rules are set per library (or “All Libraries”) with a weeks threshold.
  • When at least one rule exists, auto‑pause is enabled.

Home page & progress toggles

  • Show Planned Items on Home: disabled / combined / separated.
  • Book/Comic/Manga Progress Format: percentage vs pages/issues/chapters. For list behavior and sorting, see Home and Media Lists.

See also

Notifications

Floppy can push release alerts to any service you already use. Everything is configured under Settings → Notifications.

Apprise URLs Delivery is handled by Apprise, so a destination is expressed as a single URL. Enter one URL per line — every line receives every notification, so you can fan out to several services at once. Each line is validated when you save, and an invalid URL is rejected with the offending line quoted back to you.

A few common formats:

  • Discord: discord://webhook_id/webhook_token
  • Notifiarr: notifiarr://api_key/#channel_id
  • Telegram: tgram://bot_token/chat_id
  • ntfy: ntfy://topic

The Apprise wiki lists the full set of supported services and their URL syntax.

What gets sent

  • Release notifications: fire within ~10 minutes of an upcoming release for something you track.
  • Daily digest: a single once-per-day summary of everything releasing that day.

Both are independent toggles, so you can run one, the other, or neither.

Excluding items Search for any tracked item and add it to the exclusion list to silence it without turning notifications off entirely. Useful for long-running shows you follow but do not want pinged about weekly.

Testing Use Test Notifications on the settings page. It delivers immediately to every URL you have saved — the fastest way to confirm a key or channel ID is correct. The banner reports a single combined result, so if you have several URLs configured and see a failure, test them one at a time to find the bad line.

Notifiarr setup

Notifiarr works out of the box; no separate integration or API key field is needed.

  1. In Notifiarr, open Integrations and copy your API key.
  2. In Discord, enable Developer Mode, then right-click the target channel and Copy Channel ID.
  3. In Floppy, go to Settings → Notifications and add a line: notifiarr://<api_key>/#<channel_id>
  4. Save, then click Test Notifications.

The # prefix on the channel ID is required — it tells Apprise the target is a channel, not a comment marker. Notifications are sent as plain text, so Notifiarr and Discord render the release list cleanly.

See also

Discover

The Discover page (/discover/) surfaces personalized recommendations and global trends across all media types. It is accessible from the sidebar.

Media type selector

  • Use the tabs at the top of the page to switch between media types (Movies, TV, Anime, Books, Games, etc.).
  • Your last selected media type is remembered across visits.

Recommendation rows Discover shows up to five rows per media type. Available rows:

Row Description
Trending Right Now Items with strong current momentum globally.
All-Time Greats You Haven't Seen Highly rated items not yet in your library.
Coming Soon Upcoming releases for the selected media type.
Top Picks For You Personalized ranking using genre, keyword, studio, cast, and decade signals derived from your watch history and ratings.
Clear Out Next (TV/Anime only) In-progress shows with the fewest episodes remaining — good for clearing your backlog.
Comfort Rewatches Previously watched items that still feel ready for a fresh revisit based on your taste profile and recent rewatch freshness.

Not all rows appear for every media type; availability depends on what data is present.

Controls

  • Show More / Show Fewer — expands or collapses the number of visible rows.
  • Refresh — rebuilds recommendations on demand; results are cached between refreshes.

Personalization Top Picks and Comfort Rewatches are driven by a taste profile computed from your library. The profile weights genres, keywords, studios, cast, directors, decades, and certifications based on your completed and highly-rated items. For movie Comfort Rewatches, recent-repeat saturation is also applied so heavily replayed titles cool off before resurfacing. Items already in your library are excluded from recommendations.

Note: Some row types are marked "under construction" and may show a notice while the feature is being refined.

See also

Clone this wiki locally