Jobs and queues
How Frameleaf processes your photos: background work, queues and Activity Watch on YouTube
Almost everything Frameleaf does with a new photo or video happens in the background as jobs: reading its details, making thumbnails, finding faces, indexing it for search, transcoding videos and more. Jobs wait in queues, and the server works through them as fast as its settings allow.
Where to manage jobs
Section titled “Where to manage jobs”Open Settings, then Computers & background work, then Background work. The page has two views, chosen at the top: Everyday and Advanced.
Everyday
Section titled “Everyday”Everyday is for pace, when heavy work runs, and each feature.
The page starts with one sentence on how the work is going, such as Nothing is running, how many items the server is working through, or how many things failed. Beside it:
- Pause everything stops new work starting until you resume. Work that’s already running finishes first. This affects everyone on the server.
- Resume, or Resume all with a count, starts paused work again.
- See the failed task opens the task that failed, and Fix in Activity opens the Activity page, which says what each arrival is waiting for. When nothing failed, the button reads Open Activity.
Below that:
-
Pace has two choices. How hard this server works is Light, Balanced or Fast; see Concurrency. When heavy work runs is Overnight or Any time; see Quiet hours. Overnight schedule opens the night’s schedule.
-
Features has one row for each thing the server does for your library:
Feature What it covers Ready to browse Thumbnails, dates and places, and video copies that play everywhere Faces & identity Recognising the people and pets in your photos Visual search Finding photos by describing what’s in them Text, documents & receipts Making signs, documents and receipts searchable Descriptions & tags Captions, tags and private-photo suggestions Transcripts & captions Turning speech in a video into text. It runs when you start it from a video Studio export Making the finished video from a Studio project. It runs when you export Upkeep Duplicates, file checks, library data backups and housekeeping Each row says where the feature runs (select it to open Computers), its state, such as Running, Waiting, Paused, Up to date or Needs a look, and how many items are left. The menu at the end of the row has Pause or Resume, Catch up on what’s missing, Do it all again…, and a link to the feature’s tasks in Advanced. Descriptions & tags also has Recheck smart albums, and Upkeep has Check files for damage and Count the library now.
-
How many run at once has Jobs running at once, the most jobs the server works on together across every task. Automatic suits most servers; you can choose a number from 1 to 32 instead. Each task’s own number opens Advanced.
Advanced
Section titled “Advanced”Advanced is for tracking down a problem. Its heading counts what is running, what is waiting and what needs a look. Pause everything is here too, and Resume the one you paused (or however many) starts again only what a person paused.
Needs a look comes first. It groups everything that failed by what went wrong, across every task, with the most photos first. Each reason says which tasks it is in and has one thing to do about it. The three biggest reasons show; the rest fold away under a count.
| What went wrong | What it means | What to do |
|---|---|---|
| An external library can’t be reached | The drive or network folder the photos live on is offline. | Reconnect it, then Try again. |
| The original file is missing | The photo is in your library but its file isn’t where it should be. Library care is already looking for these. | Open Library care. |
| The file is damaged | The file is there but can’t be read all the way through. | Open Library care, which can look for a good copy. |
| A kind of file Frameleaf can’t open | The files are kept as they are and can be downloaded, but have no preview. Trying again won’t help. | Stop trying. They no longer count as failed. |
| A folder couldn’t be written to | The server isn’t allowed to save into part of the library folder. | Check the folder’s permissions, then Try again. |
| The face and search helper didn’t answer | Machine learning was off or too busy. Nothing is wrong with the photos. | Try again. |
| It took too long | A job was stopped at the longest time one job may take. Very long or very large videos do this. | Try again. |
| Something else | The server didn’t recognise the problem, so the page shows what it said. | See the jobs. |
For the other reasons, What the server said shows the server’s own words. A photo with several failed tasks counts once. Try again puts back every failed job for those photos; if one of their tasks is paused, they run when it’s resumed.
Tasks with work lists each task that is running, waiting or has failures, with why it is or isn’t running:
| The row says | What it means |
|---|---|
| Running 3 at once | The task is working now. |
| Next in line | Its jobs are waiting their turn. |
| You paused this on and a date | Someone paused the task. Resume starts it. A pause the server made itself, for example while the library is being moved, reads Paused. |
| Heavy work. Starts tonight at and a time | Quiet hours are holding it. Start now runs it straight away. |
| Waiting for another task to finish | Its next jobs each depend on work in another task. |
| This feature is off | The feature it belongs to is turned off in Settings. |
| Only failures left | Nothing is waiting; the failed jobs are all that remain. |
Each row also has how many are waiting, how many failed, how many run at once, and one button: Pause, Resume or Start now. Tasks with nothing to do fold away at the foot of the list. Type in Find a task… to search by task or feature, and select a row to open the task’s own page.
At the foot of the page:
- How many run at once sets each task’s own number. See Concurrency.
- Enrichment tasks regenerates descriptions or re-evaluates smart albums, now or later.
- Create a job starts a maintenance task, such as the database backup, the integrity checks, memory generation or the clean-up of unused people. Each one is reviewed before it runs.
- Recent work is in Activity opens the Activity page.
One task’s own page
Section titled “One task’s own page”Select a task in Advanced to open its own page. Four counts sit at the top: Processing, Waiting & scheduled, Failed and Completed in activity, the finished jobs the server still keeps a record of. Below them, the Active, Waiting, Failed and History tabs list the jobs, with the account and computer each belongs to. History shows completed work kept in this view. A finished job stays on record for an hour, and a failed or cancelled one for 30 days; the totals for each piece of work stay in Recent work and Activity. There you can:
- Pause queue and Resume queue. Each opens a review first. Pausing stops the queue taking new work: active jobs finish and delayed jobs keep their schedule. Resuming lets waiting work start, using the current concurrency limit. The review shows the scope, which is always every account, and how many items are affected now. Choose Pause queue or Resume queue to go ahead, or Keep current state to leave it as it is. A few essential kinds of work, such as Housekeeping, can’t be paused.
- Catch up to queue only the items that haven’t been processed yet. Some kinds name it after what they do, and tasks that run once say Start now.
- Do it all again to run it again for every item. For faces, Refresh faces updates results without a full reset.
- Run on one item… to run the task on one photo or video at once, even while the task is busy or paused.
- On the Failed tab, Try again puts failed jobs back with their saved inputs. Check the error and fix the cause first, so the retry succeeds. Stop trying these removes the failed records instead.
- Try again also runs work for files Frameleaf had set aside, whatever set them aside: three failures in a row, a kind of file it couldn’t open, or Stop trying. Each starts afresh, so a file whose format Frameleaf has since learned to open now gets its preview. A file that still can’t be read is set aside again after its usual tries. Automatic retries and the nightly run still skip set-aside files.
- When a failed item is for one photo whose file is damaged or missing, its details also have In Library care, which opens that photo’s history in Damaged and missing files. A photo whose preview couldn’t be made because its file is damaged doesn’t show up as failed here: Frameleaf takes it straight to Library care.
- On the Waiting tab, Clear waiting work removes jobs that haven’t started. Neither deletes any original file. A task held by quiet hours lists its waiting jobs as Scheduled, not paused.
- Open Jobs over time to see a graph of the active, waiting and failed jobs since the page opened.
Every command shows its effect on every account before it runs, and the ones that can’t be undone ask you to confirm. To see one account’s counts and jobs, choose it in Viewing at the top of Settings. The counts then cover that account’s share of the whole queue. That changes only what you see; commands still apply to the whole server.
The old Administration pages for job queues now open Background work.
What runs first
Section titled “What runs first”Frameleaf doesn’t make new photos wait behind old work. Each task takes its jobs in this order:
- Work you start by hand, such as Run on one item… or a task you start from this page.
- Work for photos that just came in: an upload from a phone or the web, an import, an upload through a shared link, or a folder scan that found new files. Their later steps, such as thumbnails after the details are read, stay ahead of the backlog too.
- The backlog: everything else, oldest first.
A job keeps its place when the server is busy or when it has to be tried again, so a new photo’s thumbnail doesn’t fall to the back of a long queue. Tasks holding this kind of work are served before the others. Quiet hours still apply: heavy work for a new photo waits for the night like any other, unless you start it.
Recent work
Section titled “Recent work”At the foot of each task’s own page are two records:
- Queue action history lists the commands sent from this device, such as a pause or a retry, and which accounts they applied to. It records commands, not finished work.
- Recent work: “Each piece of work the server has taken on, how far it has got, and anything holding it up.”
In Recent work, each piece of work is a card. It says what the work is, such as Nightly processing, Library import or Library folder scan, and when it started or finished. It says how far it has got, such as 38 of 40 photos, or in tasks for work that isn’t about photos. And it has one state, with one sentence that says why:
| State | What it means |
|---|---|
| Running | The work is going. |
| Paused | “You paused this. It carries on when you resume it.” Select Resume. When only its setup is held, select Release. When some of the steps it needs are paused elsewhere, See what is paused opens the task list. |
| Waiting for a drive | The external library it needs can’t be reached. “It carries on by itself when the drive is back.” |
| Waiting for library setup | Library setup is still checking your files. It starts when that’s done. |
| Waiting for machine learning | “It carries on by itself when machine learning is available.” |
| Machine learning is off | Machine learning is turned off for this. It carries on when you turn it on. |
| Scheduled | “Waiting for the night window. It starts by itself.” See Quiet hours. |
| Not started yet | Waiting for the server to start it, or for a computer that can run it. If it has been ready for a few minutes without starting, check Computers and the task’s settings. |
| Retrying | “Some items will be tried again shortly.” |
| Finished | Everything was done. |
| Finished, with photos left over | Most of it was done, but some photos weren’t. See When some photos are left over. |
| Needs attention | “This stopped before it finished.” Start it again from the task list when you’re ready. |
| Stopped | It was cancelled before it finished. |
The card doesn’t say when work was paused.
The Activity page, in the top bar, shows the same work in plainer terms, by feature or by what came in, and a scan that was interrupted twice as a card of its own with Scan again. It hides a failed scan once a later scan of the same library has run. For a folder that can’t be reached, Recent work says Couldn’t reach the drive where Activity says Waiting for a drive.
Nightly processing
Section titled “Nightly processing”The overnight schedule’s work is one card, Nightly processing, instead of one card for each night. It says when the last night finished. Earlier nights opens a list of the nights before, with how many photos each night took on and how many were left over.
When the same photos are left over night after night, the card says so: “The same 4 photos have been left over 3 nights in a row. Sorting them out once stops them coming back.” After a week, it says “7 or more nights”. Review them once, as below, and they stop coming back.
A few kinds of night work that start outside the overnight schedule still have their own card, named after what they do.
When some photos are left over
Section titled “When some photos are left over”When a piece of work finishes with photos left over, its card says how many, such as 4 photos need a look, and lists the causes with a count for each. Select Review what failed to open What failed in that work.
The review groups the photos by cause. Each cause says what it means and has one thing to do. “Your photos are safe either way: nothing here deletes a file.”
| Cause | What it means | What to do |
|---|---|---|
| A drive can’t be reached | The originals are on an external library that isn’t plugged in or mounted. Nothing is wrong with the photos. | Plug the drive in or mount it again. Frameleaf tries again by itself when it’s back, or select Try again now. |
| Original missing | The original file is gone. Library care is already looking for a copy, and asks your backups and phones. | Select Open in Library care. See What to do about a missing photo. |
| Damaged file | The file is cut short or won’t open. Library care may have repaired some by itself, and kept the damaged files. | Select Open in Library care. See What to do about a damaged photo. |
| A kind of file Frameleaf can’t open | The files are kept safely as they are, with no preview. Trying again only helps once Frameleaf can open their format, for example after an update. | Select Stop trying. If an update added the format, use Try again on the queue’s Failed tab instead. See Supported formats. |
| Couldn’t be finished this time | Frameleaf couldn’t finish these, often because the server was busy or a step took too long. | Select Try again now. It usually works. |
- Stop trying only stops Frameleaf trying these files again each night. The files stay as they are, and the history stays too. Try again on the queue’s Failed tab still runs them again if you ask.
- Show photos shows a few of the photos for each cause. A photo from another account shows a lock and a note such as “Only Sam sees this photo and can undo or replace it.”, never the picture.
- Technical details shows what the server reported for these photos, and Open the full list, one row per photo.
- Work recorded by an older version of Frameleaf has no causes. Its card says “Recorded before Frameleaf kept the causes.” and has Open the task list instead of Review what failed.
The queues
Section titled “The queues”These are the tasks Advanced lists. Each one belongs to a feature on the Everyday view.
| Kind of work | What it does | Default concurrency |
|---|---|---|
| Reading photo details | Reads capture dates, camera details, location and embedded metadata | 5 |
| Sort originals into folders | Moves originals into the folder layout chosen under Storage & originals, then Folder layout | |
| Making thumbnails | Makes image previews and thumbnails | 3 |
| Converting videos | Makes compatible playback copies of original videos, and the seek-bar previews of every video (Video scrubbing and previews) | 1 |
| Preparing photos for search | Indexes visual content for smart search | 2 |
| Finding faces | Finds faces before they’re matched to people | 2 |
| Recognising people | Matches detected faces to people | |
| Reading text in photos | Extracts searchable text from images | 1 |
| Finding duplicate photos | Finds visually similar photos | |
| Finding duplicate videos | Compares sampled video frames to find duplicate videos | 1 |
| Search and recognition | Schedules descriptions and Locked-content analysis | 2 |
| Writing captions | Describes photos and suggests tags | 2 |
| Suggesting private photos | Identifies images to keep Locked | 2 |
| Recognising pets | Suggests which of your pets appear in photos | 1 |
| Saving edits | Renders saved photo and video edits | 2 |
| Health checks | Inspects missing or damaged files | 2 |
| Checking for damaged files | Checks files exist, are known and match their checksums | 1 |
| Library scans | Rescans your external libraries | 5 |
| Photo detail files | Finds sidecar files or syncs their metadata | 5 |
| Moving files | Moves generated files into their current layout | 5 |
| Updating search | Maintains search records | 5 |
| Workflows | Runs your workflow actions after library events | 5 |
| Sending notifications | Delivers notifications and messages | 5 |
| Housekeeping | Clean-up, coordination and follow-up tasks | 5 |
| Backing up library data | Backs up the database |
The defaults are the Balanced pace. A blank concurrency means the kind of work has no setting of its own; these always run one at a time, in order.
What happens after an upload
Section titled “What happens after an upload”Each new upload sets off a chain of jobs:
- Metadata is read.
- Sort originals into folders moves the file, if Sort originals into folders is on in Folder layout.
- Thumbnails are made: large, small, blurred and face thumbnails.
- Then, in parallel:
- Visual search indexing, followed by duplicate detection
- Face detection, followed by face recognition
- Text recognition
- Video transcoding, for videos
- Image enrichment: descriptions, tags and Locked-content detection
Image enrichment jobs
Section titled “Image enrichment jobs”Locked-content detection (Suggesting private photos) and descriptions and tags (Writing captions) have separate queues, so you can run them independently. For example, classify Locked content first, review the results, then fill in descriptions and tags, without changing settings in between.
- When both are on, a new upload queues one description job after its thumbnails. That job runs Locked-content detection first if there’s no saved result, then passes the result to the description model.
- When only Locked-content detection is on, uploads queue it directly.
- Backfill jobs process images that have previews, and skip deleted, hidden and Locked items. A normal run skips items that already have a result; reprocessing recalculates them, but never adds duplicate
AI description:blocks or repeated tags.
See AI descriptions and smart albums.
Nightly tasks
Section titled “Nightly tasks”The server’s own night work runs from one overnight schedule, in Settings, then Computers & background work, then Overnight schedule. It starts at midnight and stops starting new steps at 6:00 AM by default, every day, on this server’s clock. The steps run one after another:
- Empty Trash and tidy up: removes items that have been in Trash longer than the keep time, and accounts deleted more than 7 days ago. It also makes missing thumbnails, groups new faces, prepares memories and recounts storage.
- Check added folders: looks for new, changed and removed files in external libraries.
- Bring in new iCloud photos, if iCloud Photos is connected.
- Check files: the integrity checks.
The night’s run also looks for photos and videos that still need previews, details, search, faces, text or a playback copy, and queues what’s missing. The switch is Finish anything that didn’t process, on by default. It skips files Frameleaf has set aside.
A step that’s switched off or not set up is left out. A step that hasn’t started by the stop time carries on the next night. Database backups keep their own schedule, and the steps that use the disk or the internet wait for a running backup to finish. Every setting is described in Overnight schedule.
Quiet hours
Section titled “Quiet hours”Quiet hours keep the server quick during the day. Heavy background work, including the AI features, waits for the overnight schedule’s window and runs then. The switch is Save heavy background work for the night, in Overnight schedule. It’s on by default. When heavy work runs on the Background work page is the same setting: Overnight is on, Any time is off.
What waits for the night:
- Converting videos, including seek-bar previews
- Finding faces and recognising people
- Finding pets
- Preparing photos for Visual search
- Looking for duplicate photos and videos
- Reading text in photos
- Enrichment, and writing AI descriptions
What never waits: uploads, reading photo details and making thumbnails. A photo from a phone uploads and shows up in the timeline straight away, at any hour. Suggesting private photos (sensitive-content detection) never waits either, so sensitive items stay hidden from the moment they arrive.
When the window is open:
- With a stop time (the default is 6:00 AM), heavy work runs from the start time to the stop time. Whatever is left waits for the next night.
- With no stop time, heavy work starts at the start time and runs until it has caught up. Then it waits until the next start time. It counts as caught up only after ten quiet minutes with nothing left to feed it, so one quiet moment doesn’t close the night early.
- The window opens only on the days chosen in the schedule. If you limit the schedule to some days, heavy work waits for the next of those days.
- Times are on this server’s clock, set by Time zone in Server name & welcome.
The window follows the schedule’s times, not its runs. Run now starts the night’s steps, but it doesn’t open the window for heavy work.
Quiet hours pause the queues for these kinds of work, so they wait wherever that work is set to run: this server, a desktop on your network or Frameleaf Cloud. Jobs that had already started when the window closed finish first. In Background work, Advanced shows a held task as Heavy work. Starts tonight at and the time, and it starts again by itself. Activity says Saved for tonight, starts at and the time.
- Starting a held task yourself, with Start now, runs it now. It stays running for the rest of the day, and quiet hours hold it again from the next night.
- A queue you paused yourself stays paused. Quiet hours never resume it.
Turn the switch off if your server has power to spare, or if you want new photos processed as soon as they arrive. Faces, search and descriptions then start straight after upload.
Concurrency
Section titled “Concurrency”Concurrency is how many jobs run at once. Raise it to clear a backlog sooner; higher values share CPU, GPU memory and disk bandwidth, and machine learning jobs use more video memory. There are two limits:
- Each task’s own number: how many jobs of that task run at the same time.
- Jobs running at once: the most jobs the server works on together, across every task. No server runs more than 32.
To set the pace for every task, open Background work and choose How hard this server works:
- Light keeps browsing fast; new uploads take longer to finish.
- Balanced is a good fit for most servers, and is the default.
- Fast finishes sooner, but browsing may feel slow while it works.
To set one task yourself:
- Open Advanced and select How many run at once, or the at once number on a task’s row.
- Enter a number for the task. Tasks that must run in order are fixed at one.
- Save it with your other settings.
If a task’s number is higher than Jobs running at once allows, the page says so and offers to raise it. Once tasks have numbers of their own, How hard this server works shows none of the three choices until you pick one again.
- These changes join the same Review changes draft as other settings.
- A new limit applies to the next jobs to start. Lowering it doesn’t cancel active jobs.
- Changing a number doesn’t move a job to another computer or retry a failure.
- If the numbers are set in the config file, they can’t be changed here. If the server was started with
FRAMELEAF_JOB_CAPACITY, Jobs running at once is fixed to that number. - If you add GPUs or split work across containers, raise the machine learning numbers to keep them busy.
Restorations aren’t in these queues and never take a queue’s slot. See Workers and where jobs run.
Inside the server container
Section titled “Inside the server container”The frameleaf_server container runs several workers:
| Worker | What it does |
|---|---|
api |
Answers requests from the web and the apps |
microservices |
Runs jobs: thumbnails, video encoding and most other background work |
edge |
Serves remote access and passes requests to api. It does nothing until remote access is on for a linked server |
Machine learning runs in its own container, or on other computers; see Workers and where jobs run.
Stopping the server
Section titled “Stopping the server”When the container stops (docker compose stop, an upgrade or a NAS package restart), each worker stops taking new work. Running jobs and requests get a grace period to finish. A job still running after that goes back to waiting, so it runs again as soon as the server is back. Jobs that could repeat a side effect, such as sending an email or a push notification, are marked failed instead.
| Variable | What it sets | Default |
|---|---|---|
FRAMELEAF_SHUTDOWN_GRACE_SECONDS |
How long running work gets to finish | 5 |
FRAMELEAF_SHUTDOWN_DEADLINE_SECONDS |
When the server exits, whatever is still running | 9 |
The grace period must be shorter than the deadline. Docker kills the container when its own stop timeout ends, so it must be longer than the deadline. The provided Compose files and NAS packages set stop_grace_period: 10s on the server (Unraid: --stop-timeout=10). Keep it if you write your own Compose file, and raise it if you raise the deadline.
If the server is killed or crashes, jobs that were running are picked up again about a minute after the next start.
Split the server into containers
Section titled “Split the server into containers”You can run the workers in separate containers, for example one for the web and API and one for background jobs, by choosing which workers each container runs:
| Variable | What it does |
|---|---|
FRAMELEAF_WORKERS_INCLUDE |
Run only these workers, comma-separated |
FRAMELEAF_WORKERS_EXCLUDE |
Run every worker except these |
- Copy the whole
frameleaf-serverblock indocker-compose.ymlas a new service. In the copy, change the service and container name and remove theportssection:
frameleaf-server: container_name: frameleaf_server ports: - 2283:2283frameleaf-microservices: container_name: frameleaf_microservices- Give each service its workers:
services: frameleaf-server: # ... environment: FRAMELEAF_WORKERS_INCLUDE: 'api,edge'
frameleaf-microservices: # ... environment: FRAMELEAF_WORKERS_EXCLUDE: 'api'By default edge runs wherever api runs. When you name workers in FRAMELEAF_WORKERS_INCLUDE, only those run, so include edge alongside api if you use remote access. A container that excludes api doesn’t run edge unless FRAMELEAF_WORKERS_INCLUDE names it. If you run edge in a different container from api, give both containers the same FRAMELEAF_EDGE_SECRET (at least 16 characters).
To spread work across several machines, see Scaling.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.


