Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Preferences
Contact Us
Feedback
AWS Documentation
Create an AWS Account

Start stream sessions with Amazon GameLift Streams

PDF
Focus mode
Start stream sessions with Amazon GameLift Streams - Amazon GameLift Streams
About stream sessionsTesting a streamStream session life cycleReconnect back to your stream

This section covers stream sessions, the actual instance of a stream where an end user or player can interact with your application or play your game. You'll learn about how to test your own stream session and understand the stream session life cycle.

For launching stream sessions to end users, you must integrate Amazon GameLift Streams into your own service. For more information, refer to Amazon GameLift Streams backend service and web client.

About stream sessions

The prerequisites to start a stream session are an application and a stream group that has available active capacity. A stream session runs on one of the compute resources, or stream capacity, that a stream group has allocated. When you start a stream, you must specify a stream group and choose to stream the default application or a linked application. By default, Amazon GameLift Streams streams the default application. To stream a linked application, specify both the stream group and application ARN when you start a stream session.

When you successfully start a stream session, you receive a unique identifier for that stream session. Then, you use that ID to connect the stream session to an end user. For more information, refer to StartStreamSession in the Amazon GameLift Streams API Reference.

Testing a stream

The most direct way for you to test how your application streams is through the Amazon GameLift Streams console. When you start a stream, Amazon GameLift Streams uses one of the compute resources that your stream group allocates. So, you must have available capacity in your stream group.

To test your stream in the Amazon GameLift Streams console

  1. Sign in to the AWS Management Console and open the Amazon GameLift Streams console.

  2. You can launch a stream in several ways. Start from the Stream groups page or Test stream page and follow these steps:

    1. Select a stream group that you want to use to stream.

    2. If you're starting from the Stream groups page, choose Test stream. If you're starting from the Test stream page, select Choose. This opens the Test stream configuration page for the selected stream group.

    3. In Linked applications, select an application.

    4. In Location, choose a location with available capacity.

    5. (Optional) In Program configurations, enter command-line arguments or environment variables to pass to the application as it launches.

    6. Confirm your selection, and choose Test stream.

  3. After your stream loads, you can do the following actions in your stream:

    1. To connect input, such as your mouse, keyboard, and gamepad, choose Attach input. You automatically attach your mouse when you move the cursor into the stream window.

    2. To have files that were created during the streaming session exported to an Amazon S3 bucket at the end of the session, choose Export files and specify the bucket details. Exported files can be found on the Sessions page.

    3. To view the stream in fullscreen, choose Fullscreen. Press Escape to reverse this action.

  4. To end the stream, choose Terminate session. When the stream disconnects, the stream capacity becomes available to start another stream.

Stream session life cycle

When working with stream sessions in Amazon GameLift Streams, this diagram can help you understand the different states that a stream session transitions to throughout its life cycle.

  • StartStreamSession creates a new stream session, which begins in ACTIVATING state. When Amazon GameLift Streams finds available resources to host the stream, the stream session transitions to ACTIVE. When a client connects to the active stream, the stream session transitions to CONNECTED.

  • When a client disconnects from a stream, the stream session transitions to PENDING_CLIENT_RECONNECTION state. CreateStreamSessionConnection transitions the stream session to RECONNECTING, and will either initiate the client to reconnect to the stream or create a new stream session. When the client reconnects, it transitions back to CONNECTED. If a client is disconnected for longer than ConnectionTimeoutSeconds, the stream session ends.

  • When a client doesn't connect to a stream session in ACTIVE or PENDING_CLIENT_RECONNECTION state within a period of time, then it transitions to TERMINATED.

  • TerminateStreamSession initiates termination of the stream, and the stream session transitions to TERMINATING state. When the stream session terminates successfully, it transitions to TERMINATED.

  • A stream session in any state, except TERMINATED, can transition to ERROR. You can find additional details about the error in Amazon GameLift Streams Console or CLI.

This diagram shows the different states that a stream session transitions to throughout its life cycle.

Reconnect back to your stream

If you refresh the website, switch browsers, or disconnect from your stream in some way, you can reconnect back to your stream within a grace period.

Each stream connection has a unique token that must be specified to reconnect back to that stream. In this Amazon GameLift Streams Web SDK sample web client, the stream's unique token is located in the URL address. For example: http://localhost:8000/?token=2061cf1b-4bef-bf3e-e39165924480.

For more information, refer to CreateStreamSessionConnection in the Amazon GameLift Streams API Reference.

On this page

PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.