jake
b289b7abed
- Skip recommendations refresh for titles fetched within the last 7 days via `getTitlesWithFreshRecommendations`; only stale titles are re-fetched - Replace `Promise.allSettled` in `refreshTvChildren` with a `mapWithConcurrency` helper (concurrency = 5) to stay within TMDB's rate limit - Add 30s request timeout middleware to TMDB client to prevent indefinitely hung fetches - Expand `optimizeDb` weekly job to prune 30-day-old cron runs, integration events, expired sessions, and expired verifications - Add `wal_checkpoint(TRUNCATE)` to `optimizeDatabase` so the WAL is flushed before `PRAGMA optimize` - Add `recoverStaleImportJobs` called on server startup to mark any `pending`/`running` import jobs as errored after a crash/restart - Return `false` from `triggerJob` immediately if the job is already running
7.2 KiB
title, description, icon
| title | description | icon |
|---|---|---|
| Using Sofa | A guide to tracking movies and TV shows with Sofa. | Compass |
Dashboard
The dashboard is your home screen after logging in. It shows a personalized overview of your tracking activity.
- Stats — Cards showing movies watched, episodes watched, library size, and completed titles. Each card has a period selector (today, this week, this month, this year) and a sparkline chart of your watch history.
- Continue Watching — TV shows you're currently watching, with the next unwatched episode highlighted. Click a show to jump to its detail page and pick up where you left off.
- Upcoming — Episodes and releases airing in the next 7 days for titles in your library. Click "View all" to open the full upcoming page with episodes grouped by date (Today, Tomorrow, This Week, Later).
- In Your Library — A grid of all titles you're tracking, regardless of status.
- Recommended for You — Personalized suggestions based on titles you've watched and rated highly.
If your library is empty, the dashboard shows an invitation to start exploring.
Tracking Movies & TV Shows
The Status System
Every title in your library has a status:
| Status | Meaning |
|---|---|
| Watchlist | You plan to watch this |
| Watching | You're currently watching this (TV shows only) |
| Caught Up | You've watched all aired episodes, but the show is still airing (TV only) |
| Completed | You've finished watching this |
Click the status button on a title page to add it to your watchlist. If the title is already in your library, hovering the button reveals a "Remove" action. Press W to toggle the title in or out of your watchlist.
**Caught Up** vs **Completed** is automatic — when you've watched every episode of a TV show that is still airing (Returning Series or In Production on TMDB), Sofa shows **Caught Up** instead of **Completed**. Once the show ends, it switches to **Completed** automatically.Automatic Status Transitions
Sofa automatically updates statuses as you log watches so you don't have to manage them manually:
- First episode watched on a TV show → status changes to Watching (if it was on your Watchlist or had no status)
- All episodes watched on a TV show → status changes to Caught Up (if the show is still airing) or Completed (if the show has ended)
- Unwatch an episode on a completed show → status drops back to Watching
- Unwatch all episodes on a show → status drops back to Watchlist
- Mark a movie as watched → status changes to Completed
These same transitions apply when watches are logged automatically via webhook integrations (Plex, Jellyfin, Emby) or imported from another app (Trakt, Simkl, Letterboxd).
Logging Watches
Movies: Click the Mark Watched button on the title page (or press M) to log a watch and mark the movie as completed.
TV episodes: On the title page, expand a season and toggle individual episodes. You can also:
- Mark an entire season — Click the checkmark button on a season header to mark all its episodes as watched.
- Mark all episodes — Mark the entire show as watched in one action.
- Catch up — When you mark an episode as watched while earlier episodes are unwatched, a toast notification offers a "Catch up" button to batch-mark all prior episodes.
Rating Titles
Rate any title from 1 to 5 stars on its detail page. Click a star to set the rating, or click the same star again to clear it. You can also press 1 through 5 on a title page to rate with the keyboard.
Ratings are independent of status — you can rate a title at any point, whether it's on your watchlist or completed. Highly-rated titles contribute to your personalized recommendations.
Exploring & Discovering Content
The Explore page helps you find new things to watch:
- Hero banner — A featured trending title with backdrop, rating, and overview.
- Trending Today — A scrollable row of titles currently trending on TMDB.
- Popular Movies — Browse popular movies, filterable by genre using the dropdown.
- Popular TV Shows — Browse popular TV shows, also filterable by genre.
Title cards show your tracking status as an overlay, so you can see at a glance which titles you've already added to your library.
Search
Press / or ⌘K (Mac) / Ctrl+K (Windows) to open the command palette. Start typing to search movies, TV shows, and people via TMDB.
Results show a poster or profile photo, type badge (Movie, TV, or Person), release year, and rating. Click a result to navigate to its detail page.
The command palette also shows:
- Recent searches — Your last few searches, with options to re-run or clear them.
- Quick actions — Shortcuts to navigate to the dashboard or explore page.
Streaming Availability
Title detail pages include a Where to Watch section showing which streaming services carry the title. Providers are grouped by offer type:
- Stream — Available with a subscription (Netflix, Disney+, etc.)
- Rent — Available to rent digitally
- Buy — Available to purchase digitally
- Free — Available for free
- With Ads — Available on ad-supported tiers
Click a provider's logo to open their page for that title in a new tab.
Streaming availability data is currently limited to the **United States**. Provider information is refreshed automatically every 6 hours for titles in your library.Account Management
Manage your profile in Settings:
- Display name — Click your name to edit it inline.
- Profile picture — Click your avatar to upload a new image (JPEG, PNG, WebP, or GIF) or remove the current one.
- Change password — Available for email/password accounts. Not shown for OIDC/SSO-only accounts.
Keyboard Shortcuts
Press ? anywhere in the app to see the full shortcut reference. Here's a summary:
| Scope | Keys | Action |
|---|---|---|
| Global | / |
Open search |
| Global | ? |
Show keyboard shortcuts |
| Navigation | g then h |
Go to dashboard |
| Navigation | g then e |
Go to explore |
| Navigation | g then u |
Go to upcoming |
| Navigation | g then s |
Go to settings |
| Title page | w |
Toggle watchlist |
| Title page | m |
Mark movie as watched |
| Title page | Escape |
Go back |
| Title page | 1–5 |
Rate 1–5 stars |