Start stream sessions with Amazon GameLift Streams - Amazon GameLift Streams
About stream sessionsTesting a streamStream session lifecycleTimeout values affecting stream sessionsReconnect back to your stream

Start stream sessions with Amazon GameLift Streams

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 lifecycle.

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 an application to stream using their ARN or ID values.

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 test 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 (except microphones, which are not supported in Test stream), 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.

Note

The Test stream feature in the Amazon GameLift Streams console does not support microphones.

Stream session lifecycle

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 lifecycle.

  • 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 a stream session is ready for the client to reconnect, it transitions to ACTIVE. 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 the period of time specified by ConnectionTimeoutSeconds, 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. When an API call returns ERROR as a Status value, check the value of StatusReason for a short description of the cause of the error. You can also call GetStreamSession to check these values.

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

Timeout values affecting stream sessions

Stream sessions are governed by several timeout values that control different aspects of the session lifecycle. In roughly chronological order of when you might typically encounter them during the stream session lifecycle, they include the following:

Placement timeout

Time limit for Amazon GameLift Streams to find compute resources to host a stream session using available capacity. Placement timeout varies based on the capacity type used to fulfill your stream request:

  • Always-on capacity: 75 seconds

  • On-demand capacity:

    • Linux/Proton runtimes: 90 seconds

    • Windows runtime: 10 minutes

  • Behavior: If Amazon GameLift Streams cannot identify available resources within this time, the stream session Status changes to ERROR with a StatusReason of placementTimeout.

Connection timeout

Length of time Amazon GameLift Streams waits for a client to connect or reconnect to a stream session.

  • Parameter: ConnectionTimeoutSeconds in StartStreamSession

  • Range: 1 - 3600 seconds (1 hour)

  • Default: 120 seconds (2 minutes)

  • Behavior: Timer starts when the stream session reaches ACTIVE or PENDING_CLIENT_RECONNECTION status. If no client connects before the timeout, the session Status transitions to TERMINATED.

Idle timeout

Length of time that a stream session can be idle with no user input.

  • Parameter: (internal)

  • Value: 60 minutes

  • Behavior: If no user input is received during this time, Amazon GameLift Streams terminates the stream session.

Session length timeout

Maximum duration Amazon GameLift Streams keeps a stream session open.

  • Parameter: SessionLengthSeconds in StartStreamSession

  • Range: 1 - 86400 seconds (24 hours)

  • Default: 43200 seconds (12 hours)

  • Behavior: Terminates the stream session regardless of any existing client connection when the time limit is reached.

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 the time specified by ConnectionTimeoutSeconds when the stream session was started.

Each stream connection has a unique token that must be specified to reconnect back to that stream. In the 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.