Functions that allow the game to add events to the timeline that is displayed alongside recorded video.

See Steam Timelines and diagram at the bottom of page for more information.

Member Functions

Member functions for ISteamTimeline are called through the global accessor function SteamTimeline.

SetTimelineTooltip

Name	Type	Description
pchDescription	const char *	A localized string in the language returned by SteamUtils()->GetSteamUILanguage()
flTimeDelta	float	The time offset in seconds to apply to this state change. Negative times indicate an event that happened in the past.

Sets a description (B) for the current game state in the timeline. These help the user to find specific
moments in the timeline when saving clips. Setting a new state description replaces any previous
description.

Examples could include:

• Where the user is in the world in a single player game
  
• Which round is happening in a multiplayer game
  
• The current score for a sports game

ClearTimelineTooltip

Name	Type	Description
flTimeDelta	float	The time offset in seconds to apply to this state change. Negative times indicate an event that happened in the past.

Clears the previous set game state in the timeline.

AddInstantaneousTimelineEvent

Name	Type	Description
pchTitle	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
pchDescription	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
pchIcon	const char *	The name of the icon to show at the timeline at this point. This can be one of the icons uploaded through the Steamworks partner Site for your title, or one of the provided icons that start with steam_. The Steam Timelines overview includes a list of available icons.
unPriority	uint32	Provide the priority to use when the UI is deciding which icons to display in crowded parts of the timeline. Events with larger priority values will be displayed more prominently than events with smaller priority values. This value must be between 0 and k_unMaxTimelinePriority.
flStartOffsetSeconds	float	The time offset in seconds to apply to the start of the event. Negative times indicate an event that happened in the past. One use of this parameter is to handle events whose significance is not clear until after the fact. For instance if the player starts a damage over time effect on another player, which kills them 3.5 seconds later, the game could pass -3.5 as the start offset and cause the event to appear in the timeline where the effect started.
ePossibleClip	ETimelineEventClipPriority	Allows the game to describe events that should be suggested to the user as possible video clips.

Use this to mark an event (A) on the Timeline. This event will be instantaneous. (See AddRangeTimelineEvent to add events that happened over time.)

Examples could include:

• picking up a new weapon or ammo
  
• scoring a goal

The game can nominate an event as being suitable for a clip by passing k_ETimelineEventClipPriority_Standard or k_ETimelineEventClipPriority_Featured to ePossibleClip. Players can make clips of their own at any point, but this lets the game suggest some options to Steam to make that process easier for players.

This function returns a TimelineEventHandle_t that can be used with RemoveTimelineEvent or the overlay functions DoesEventRecordingExist and OpenOverlayToTimelineEvent.

AddRangeTimelineEvent

Name	Type	Description
pchTitle	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
pchDescription	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
pchIcon	const char *	The name of the icon to show at the timeline at this point. This can be one of the icons uploaded through the Steamworks partner Site for your title, or one of the provided icons that start with steam_. The Steam Timelines overview includes a list of available icons.
unPriority	uint32	Provide the priority to use when the UI is deciding which icons to display in crowded parts of the timeline. Events with larger priority values will be displayed more prominently than events with smaller priority values. This value must be between 0 and k_unMaxTimelinePriority.
flStartOffsetSeconds	float	The time offset in seconds to apply to the start of the event. Negative times indicate an event that happened in the past. One use of this parameter is to handle events whose significance is not clear until after the fact. For instance if the player starts a damage over time effect on another player, which kills them 3.5 seconds later, the game could pass -3.5 as the start offset and cause the event to appear in the timeline where the effect started.
flDurationSeconds	float	The duration of the event, in seconds. Pass 0 for instantaneous events.
ePossibleClip	ETimelineEventClipPriority	Allows the game to describe events that should be suggested to the user as possible video clips.

Use this to mark an event (A) on the Timeline that takes some amount of time to complete.

Examples could include:

• a boss battle
  
• an impressive combo
  
• a large team fight

The game can nominate an event as being suitable for a clip by passing k_ETimelineEventClipPriority_Standard or k_ETimelineEventClipPriority_Featured to ePossibleClip. Players can make clips of their own at any point, but this lets the game suggest some options to Steam to make that process easier for players.

This function returns a TimelineEventHandle_t that can be used with RemoveTimelineEvent or the overlay functions DoesEventRecordingExist and OpenOverlayToTimelineEvent.

StartRangeTimelineEvent

Name	Type	Description
pchTitle	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
pchDescription	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
pchIcon	const char *	The name of the icon to show at the timeline at this point. This can be one of the icons uploaded through the Steamworks partner Site for your title, or one of the provided icons that start with steam_. The Steam Timelines overview includes a list of available icons.
unPriority	uint32	Provide the priority to use when the UI is deciding which icons to display in crowded parts of the timeline. Events with larger priority values will be displayed more prominently than events with smaller priority values. This value must be between 0 and k_unMaxTimelinePriority.
flStartOffsetSeconds	float	The time offset in seconds to apply to the start of the event. Negative times indicate an event that happened in the past. One use of this parameter is to handle events whose significance is not clear until after the fact. For instance if the player starts a damage over time effect on another player, which kills them 3.5 seconds later, the game could pass -3.5 as the start offset and cause the event to appear in the timeline where the effect started.
ePossibleClip	ETimelineEventClipPriority	Allows the game to describe events that should be suggested to the user as possible video clips.

Use this to mark the start of an event (A) on the Timeline that takes some amount of time to complete. The duration of the event is determined by a matching call to EndRangeTimelineEvent. If the game wants to cancel an event in progress, they can do that with a call to RemoveTimelineEvent.

The event in progress can be updated any number of times with UpdateRangeTimelineEvent.

The game can nominate an event as being suitable for a clip by passing k_ETimelineEventClipPriority_Standard or k_ETimelineEventClipPriority_Featured to ePossibleClip. Players can make clips of their own at any point, but this lets the game suggest some options to Steam to make that process easier for players.

UpdateRangeTimelineEvent

Name	Type	Description
ulEvent	TimelineEventHandle_t	Handle of the event to update.
pchTitle	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
pchDescription	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
pchIcon	const char *	The name of the icon to show at the timeline at this point. This can be one of the icons uploaded through the Steamworks partner Site for your title, or one of the provided icons that start with steam_. The Steam Timelines overview includes a list of available icons.
unPriority	uint32	Provide the priority to use when the UI is deciding which icons to display in crowded parts of the timeline. Events with larger priority values will be displayed more prominently than events with smaller priority values. This value must be between 0 and k_unMaxTimelinePriority.
flStartOffsetSeconds	float	The time offset in seconds to apply to the start of the event. Negative times indicate an event that happened in the past. One use of this parameter is to handle events whose significance is not clear until after the fact. For instance if the player starts a damage over time effect on another player, which kills them 3.5 seconds later, the game could pass -3.5 as the start offset and cause the event to appear in the timeline where the effect started.
ePossibleClip	ETimelineEventClipPriority	Allows the game to describe events that should be suggested to the user as possible video clips.

Use this to update the details of an event that was started with StartRangeTimelineEvent.

EndRangeTimelineEvent

Name	Type	Description
ulEvent	TimelineEventHandle_t	Handle of the event to end.
flEndOffsetSeconds	float	The time offset in seconds to apply to the end of the event. Negative times indicate an event that happened in the past.

RemoveTimelineEvent

Name	Type	Description
ulEvent	TimelineEventHandle_t	Handle of the event to remove.

Use this to remove an event that was added with AddInstantaneousTimelineEvent or AddRangeTimelineEvent or an event that is in progress and was started with StartRangeTimelineEvent.

DoesEventRecordingExist

Name	Type	Description
ulEvent	TimelineEventHandle_t	Handle of the event to check for recordings.

Use this to determine if video recordings exist for the specified event. Steam will sent a SteamTimelineEventRecordingExists_t callback with the result. This can be useful when the game needs to decide whether or not to show a control that will call OpenOverlayToTimelineEvent.

Returns: SteamAPICall_t to be used with a SteamTimelineEventRecordingExists_t call result.

StartGamePhase

Use this to start a game phase. Game phases allow the user to navigate their background recordings and clips. Exactly what a game phase means will vary game to game, but the game phase should be a section of gameplay that is usually between 10 minutes and a few hours in length, and should be the main way a user would think to divide up the game. These are presented to the user in a UI that shows the date the game was played, with one row per game slice. Game phases should be used to mark sections of gameplay that the user might be interested in watching.

Examples could include:

• A single match in a multiplayer PvP game
  
• A chapter of a story-based singleplayer game
  
• A single run in a roguelike

Game phases are started with StartGamePhase, and while a phase is still happening, they can have tags and attributes added to them with AddGamePhaseTag or SetGamePhaseAttribute. Only one game phase can be active at a time.

EndGamePhase

Use this to end a game phase that was started with StartGamePhase.

SetGamePhaseID

Name	Type	Description
pchPhaseID	const char *	A game-provided persistent ID for a game phase. This could be a the match ID in a multiplayer game, a chapter name in a single player game, the ID of a character, etc.

The phase ID is used to let the game identify which phase it is referring to in calls to DoesGamePhaseRecordingExist or OpenOverlayToGamePhase. It may also be used to associated multiple phases with each other.

DoesGamePhaseRecordingExist

Name	Type	Description
pchPhaseID	const char *	A game-provided persistent ID for a game phase.

Use this to determine if video recordings exist for the specified game phase. Steam will sent a SteamTimelineGamePhaseRecordingExists_t callback with the result. This can be useful when the game needs to decide whether or not to show a control that will call OpenOverlayToGamePhase.

Returns: SteamAPICall_t to be used with a SteamTimelineGamePhaseRecordingExists_t call result.

AddGamePhaseTag

Name	Type	Description
pchTagName	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
pchIcon	const char *	The name of the icon to show when the tag is shown in the UI. This can be one of the icons uploaded through the Steamworks partner Site for your title, or one of the provided icons that start with steam_. The Steam Timelines overview includes a list of available icons.
pchTagGroup	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage(). Tags within the same group will be shown together in the UI.
unPriority	uint32	Provide the priority to use when the UI is deciding which icons to display. Tags with larger priority values will be displayed more prominently than tags with smaller priority values. This value must be between 0 and k_unMaxTimelinePriority.

Use this to add a game phase tag (F). Phase tags represent data with a well defined set of options, which could be data such as match resolution, hero played, game mode, etc. Tags can have an icon in addition to a text name. Multiple tags within the same group may be added per phase and all will be remembered. For example, AddGamePhaseTag may be called multiple times for a "Bosses Defeated" group, with different names and icons for each boss defeated during the phase, all of which will be shown to the user.

SetGamePhaseAttribute

Name	Type	Description
pchAttributeGroup	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
pchAttributeValue	const char *	Title-provided localized string in the language returned by SteamUtils()->GetSteamUILanguage().
unPriority	uint32	Provide the priority to use when the UI is deciding which attributes to display. Attributes with larger priority values will be displayed more prominently than attributes with smaller priority values. This value must be between 0 and k_unMaxTimelinePriority.

Use this to add a game phase attribute (E). Phase attributes represent generic text fields that can be updated throughout the duration of the phase. They are meant
to be used for phase metadata that is not part of a well defined set of options. For example, a KDA attribute that starts
with the value "0/0/0" and updates as the phase progresses, or something like a played-entered character name. Attributes
can be set as many times as the game likes with SetGamePhaseAttribute, and only the last value will be shown to the user.

SetTimelineGameMode

Name	Type	Description
eMode	ETimelineGameMode	The mode that the game is in.

Changes the color of the timeline bar (C). See ETimelineGameMode for how to use each value.

OpenOverlayToGamePhase

Name	Type	Description
pchPhaseID	const char *pchPhaseID	The game phase to show in the overlay.

Opens the Steam overlay to the section of the timeline represented by the game phase.

OpenOverlayToTimelineEvent

Name	Type	Description
ulEvent	TimelineEventHandle_t	Handle of the event to show in the overlay.

Opens the Steam overlay to the section of the timeline represented by the timeline event. This event must be in the current game session, since TimelineEventHandle_t values are not valid for future runs of the game.

Callbacks

These are callbacks that can be fired by calling SteamAPI_RunCallbacks. These will be fired directly in response to the member functions of ISteamTimeline.

SteamTimelineGamePhaseRecordingExists_t

Called when asking if recordings exist for a game phase ID.

Name	Type	Description
m_rgchPhaseID	char[ k_cchMaxPhaseIDLength ]	The phase ID that this result corresponds with
m_ulRecordingMS	uint64	The total length of the recordings in this phase in milliseconds
m_ulLongestClipMS	uint64	The total length of the longest clip in this phase in milliseconds
m_unClipCount	uint32	The number of clips that include video from this phase
m_unScreenshotCount	uint32	The number of screenshots the user has from this phase

SteamTimelineEventRecordingExists_t

Called when asking if recordings exist for an event handle.

Name	Type	Description
m_ulEventID	TimelineEventHandle_t	The handle of the event that was asked about
m_bRecordingExists	bool	This is true if recording exists for the requested event handle

Associated Functions: DoesEventRecordingExist

Enums

These are enums which are defined for use with ISteamTimeline.

ETimelineGameMode

Controls the color of the timeline bar segments. The value names listed here map to a multiplayer game, where the user starts a game (in menus), then joins a multiplayer session that first has a character selection lobby then finally the multiplayer session starts. However, you can also map these values to any type of game. In a single player game where you visit towns & dungeons, you could set k_ETimelineGameMode_Menus when the player is in a town buying items, k_ETimelineGameMode_Staging for when a dungeon is loading and k_ETimelineGameMode_Playing for when inside the dungeon fighting monsters.

Name	Value	Description
k_ETimelineGameMode_Playing	1	The player is fully loaded into the game and playing.
k_ETimelineGameMode_Staging	2	The player is in a multiplayer lobby.
k_ETimelineGameMode_Menus	3	The player is in the game's main menu or a pause menu.
k_ETimelineGameMode_LoadingScreen	4	The player is waiting for a loading screen.

ETimelineEventClipPriority

Used in AddTimelineEvent, where Featured events will be offered before Standard events.

Name	Value	Description
k_ETimelineEventClipPriority_None	1	This event is not appropriate as a clip.
k_ETimelineEventClipPriority_Standard	2	The user may want to make a clip around this event.
k_ETimelineEventClipPriority_Featured	3	The player will be likely to want a clip around event, and those clips should be promoted more prominently than clips with the k_ETimelineEventClipPriority_Standard priority.

Typedefs

TimelineEventHandle_t

Used to identify a single timeline event, which may still be in progress or may be completed. These handles are only valid for the current run of the game, and may not be used after the game is restarted.

Diagrams