# Queueing

The Cast framework provides queueing APIs that support the creation of lists of
content items, such as video or audio streams, to play sequentially on the Web
Receiver. The queue of content items may be edited, reordered, updated, and so
forth.

> [!NOTE]
> **Note:** Review the [Google Cast Autoplay](https://developers.google.com/cast/docs/design_checklist/cast-autoplay) for best practices when designing an autoplay or queueing experience for Cast.

The Web Receiver SDK maintains the queue and responds to operations on the
queue as long as the queue has at least one item currently active (playing or
paused). Senders can join the session and add items to the queue. The receiver
maintains a session for queue items until the last item completes playback or
the sender stops the playback and terminates the session, or until a sender
loads a new queue on the receiver. The receiver does not maintain any
information about terminated queues by default. Once the last item in the queue
finishes, the media session ends and the queue vanishes.

> [!NOTE]
> **Note:** The [Styled](https://developers.google.com/cast/docs/styled_receiver) and [Default Media](https://developers.google.com/cast/docs/web_receiver#default_media_web_receiver) Receivers only support a queue of audio or video streams. To use a queue of images, you must develop a [Custom Receiver](https://developers.google.com/cast/docs/web_receiver/basic).

## Create and load media queue items

In iOS, a media queue item is represented in the Cast framework as a
[`GCKMediaQueueItem` instance](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_queue_item).
When you create a media queue item with adaptive content, you can set the
preload time so that the player can begin buffering the media queue item before
the item ahead of it in the queue finishes playing. See more about preloading in
the
[Web Receiver preloading guide](https://developers.google.com/cast/docs/web_receiver/core_features#content_preload).

Setting the item's autoplay
attribute to true allows the Web Receiver to play it automatically. For example,
you can use a builder pattern to create your media queue item as follows:
Swift

```swift
let builder = GCKMediaQueueItemBuilder.init()
builder.mediaInformation = mediaInformation
builder.autoplay = true
builder.preloadTime = 8.0
let newItem = builder.build()
```
Objective-C

```objective-c
GCKMediaQueueItemBuilder *builder = [[GCKMediaQueueItemBuilder alloc] init];
builder.mediaInformation = self.mediaInformation;
builder.autoplay = YES;
builder.preloadTime = 8.0;
GCKMediaQueueItem *newItem = [builder build];
```

Load an array of media queue items in the queue by using the appropriate
`queueLoadItems` method of the
[`GCKRemoteMediaClient`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_remote_media_client)
class.

## Receive media queue status update

When the Web Receiver loads a media queue item, it assigns a unique ID to the
item that persists for the duration of the session (and the life of the queue).
You can learn the status of the queue indicating which item is currently loaded
(it might not be playing), loading, or preloaded. You can also get an ordered
list of all the items in the queue. The
[`GCKMediaStatus`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_status)
class provides this status information:

- [`preloadedItemID`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_status#aca544cb983806b859c0d62c6e1438150) property - The ID of the item that is currently preloaded, if any.
- [`loadingItemID`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_status#a0676da67792f35cbea8de2bc9015b05d) property - The ID of the item that is currently loading,
- [`currentItemID`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_status#a1818b62cd378f6648d06042dce494c58) property - The ID of the current queue item, if any.
- [`queueItemCount`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_status#a2ba0ff0a3da66b18520c2858388bc58d) method - Returns the number of items in the playback queue.
- [`queueItemAtIndex`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_status#ad1417e02dca50f0cfd5841c614bd41fa) method - Returns the item at the specified index in the playback queue.

Use these members together with the other media status members to inform your
app about the status of the queue and the items in the queue. In addition to
media status updates from the Web Receiver, you can listen for changes to the
queue by implementing `-[remoteMediaClientDidUpdateQueue:]` of the
[`GCKRemoteMediaClientListener`](https://developers.google.com/cast/docs/reference/ios/protocol_g_c_k_remote_media_client_listener-p).

> [!NOTE]
> **Note:** To provide the best user experience, the sender app must show the next autoplay item in the queue in the sender UI.

## Edit the queue

To work with the items in the queue, use the queue methods of
[`GCKRemoteMediaClient`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_remote_media_client).
you have several APIs. These let you load an array of items into a new queue,
insert items into an existing queue, update the properties of items in the
queue, make an item jump forward or backward in the queue, set the properties of
the queue itself (for example, change the `repeatMode` that selects the next
item), remove items from the queue, and reorder the items in the queue.