A Queue Is a Promise About Time
OmniGet's queue answers a question that a downloader alone cannot: what is happening to this job now, what will happen next, and what control does the user still have? This chapter focuses on the queue as a lifecycle rather than a list of links. By the end, readers can interpret states such as queued, active, paused, seeding, complete, and error, and can see why progress, scheduling, retry, and cancellation need explicit ownership.
The need becomes visible when several sources are pasted together. One item may still be fetching metadata, another may be downloading audio, a third may be waiting for a scheduled time, and a torrent may have finished transferring but still be seeding. A single percentage cannot describe all of those situations. The queue gives each item a state and gives the application a way to decide which work is allowed to occupy the next slot.
The lifecycle has meanings, not just labels
A queued item is accepted work that has not yet claimed an active transfer slot. It may be waiting behind other jobs, waiting for a scheduled start time, or waiting for a retry delay. “Queued” therefore does not mean that nothing has happened; the URL may already have preview metadata, quality choices, cookies, or a captured manifest attached to it. It means the queue has not yet handed the item to its active execution path.
An active item has claimed a slot and is allowed to fetch information or transfer media. It can move through phases such as fetching information, starting, downloading video or audio, merging, finalizing, or stalled. Those phases are not all separate terminal states. They are the queue's current explanation of what the active job is doing, and they can change as the underlying acquisition route changes from one stream to another.
Paused means that the user has deliberately stopped active progress without discarding the item. For ordinary process-backed downloads, OmniGet pauses the underlying process and records the paused state; for torrent work, the session has its own pause behavior. Resuming is therefore more than changing a label. The queue must successfully resume the underlying resource before it can truthfully return the item to active work.
Seeding is specific to a torrent lifecycle. The requested content may already be complete locally, but the torrent session remains active to share pieces. That is a different user decision from an ordinary complete download. A user may want the file but not continued seeding, or may intentionally leave the torrent available. Treating both as “complete” would hide an ongoing resource commitment.
Complete means that the queue accepted a successful result and has a usable output path or torrent state. Error means the item stopped without that result and carries a message plus a judgment about whether retry is meaningful. Cancellation is not a transient network failure. It is a user decision and should not quietly re-enter the retry path.