# Create a real-time stream

This operation creates a real-time stream.

Endpoint: POST /real_time
Version: v2.0

## Request fields (application/json):

  - `real_time_stream` (object)
    Example: {"name":"MyRealTimeStream","description":"This is my first real-time stream."}

  - `real_time_stream.name` (string, required)
    A descriptive name for the real-time stream. Maximum 255 characters.

Note:  If you record a real-time stream, the name is used to for the recording file name. To avoid file management issues in storage, Wowza Video removes or replaces special  characters in file names, so the recording file name might vary from the name you provided here.
    Example: "MyRealTimeStream"

  - `real_time_stream.description` (string)
    An optional description of the real-time stream.
    Example: "This is my first real-time stream."

  - `real_time_stream.disable_vod_encoder` (boolean)
    Skips VOD encoding and only creates an MP4 file for download. No VOD stream is created from the real-time stream. 

Can only be set when recording is true and you can't change this value after you create the stream.

Default: false

Example: "disable_vod_encoder": true

  - `real_time_stream.enable_secure_viewer` (boolean)
    Require viewers to pass a security token for playback.

Example: "enable_secure_viewer": false

  - `real_time_stream.expires_on` (string)
    The date and time the security token expires. Specify YYYY-MM-DD HH:MM:SS, where HH is a 24-hour clock in UTC. If you don't specify HH:MM:SS, the token expires at 12AM UTC on the specified day.

Required when enable_secure_viewer is true.

Example: "expires_on": "2021-10-27 23:08:55 UTC"

  - `real_time_stream.region` (string)
    An option to set the regional server the stream is distributed through. Select the region closest to your broadcast location for the most reliable stream. If you select the auto option, Wowza Video selects the region based on the publisher's location.

Default: phoenix

Example: "region": amsterdam
    Enum: "phoenix", "amsterdam", "singapore", "bangalore", "auto"

  - `real_time_stream.recording` (boolean)
    If true, records the real-time stream so you can download an MP4 later. The recording starts when the stream starts and stops automatically when the stream stops.

Recordings for real-time streams capture up to twelve hours of content in a single MP4 file. If the real-time stream recording is longer twelve hours, you'll have multiple files for the recording. 

Default: false

Note: You can't update this value after you create the stream.

Example: "recording": true

  - `real_time_stream.reference_id` (string)
    A unique, alphanumeric ID returned in real-time stream webhook payloads. Setting a reference_id is useful if you have an ID in your system or application you want to associate with real-time stream events that trigger webhooks. Maximum 70 characters. Can only contain: a-z A-Z 0-9 !@#$%^&*()-_+=:;,.?~|

You can't use brackets or quotation marks.

See Wowza Video Webhook Event Reference Documentation to learn about webhooks.

Available from version 1.12.

Example: "reference_id": "mySystemID_01"

  - `real_time_stream.enable_player_and_hosted_page` (boolean)
    If true, enables a player and hosted page for the real-time stream.

Default: true

Note: You can't update this value after you create the stream.

Example: "enable_player_and_hosted_page": true

  - `real_time_stream.player` (object)
    The player object is deprecated in 2.0. Create and update player configurations in the user interface. 

Any values you send using the player object will be ignored.

The following fields have been moved outside of the player object and reside within the real_time_stream object where you can still access them through the API:
  * logo_image
  * logo_position
  * video_poster_image
  * width

  - `real_time_stream.player.plugins` (object)
    Configuration of the plugins.

  - `real_time_stream.player.plugins.airplay` (boolean)
    If true, enables Airplay functionality in the player which allows you to cast to an Airplay device. The default is false.

Example: "airplay": false

  - `real_time_stream.player.plugins.chromecast` (boolean)
    If true, enables Chromecast functionality in the player which allows you to cast to a Chromecast device. The default is false.

Example: "chromecast": false

  - `real_time_stream.player.customizations` (object)
    Configuration of the player customizations.

  - `real_time_stream.player.customizations.play_icon` (string)
    A play icon that is displayed on the video preview. The default, solid, uses the standard play (solid triangle) icon. outlined uses an alternate (outlined triangle) play icon. ring uses an alternate (small solid triangle enclosed in a circle) play icon.

Default: solid

Example: "play_icon": "solid"
    Enum: "solid", "outlined", "ring"

  - `real_time_stream.player.customizations.thin_timeline` (boolean)
    If true, displays a thinner control bar than the default in the video. The default is false.

Example: "thin_timeline": false

  - `real_time_stream.player.customizations.drag_handle` (boolean)
    If true, displays a drag handle on the progress bar. The default is false.

Example: "drag_handle": false

  - `real_time_stream.player.customizations.volume` (boolean)
    If true, displays a volume button on the video. The default is true.

Example: "volume": true

  - `real_time_stream.player.customizations.mute` (boolean)
    If true, displays a mute button on the video. The default is true.

Example: "mute": true

  - `real_time_stream.player.customizations.fullscreen` (boolean)
    If true, displays a fullscreen button on the video. The default is true.

Example: "fullscreen": true

  - `real_time_stream.player.customizations.show_player_title` (boolean)
    If true, displays a preview title on the video. The default is false.

Example: "show_player_title": false

  - `real_time_stream.player.customizations.color` (string)
    The color of the timeline and volume bar of the player. You can set the color of your choice by passing a hex code for that specific color.

Example: "color": "4d4d4d"

  - `real_time_stream.player.video_poster_image` (string)
    The path to a GIF, JPEG, or PNG poster image that appears in the player before the stream begins. Poster image files must be 2.5 MB or smaller.

Example: "video_poster_image": "[Base64-encoded string representation of GIF, JPEG, or PNG file]"

  - `real_time_stream.player.logo_image` (string)
    A Base64-encoded string representation of a GIF, JPEG, or PNG logo  file that appears partially transparent in a corner of the player throughout playback. Logo file must be 2.5 MB or smaller.

Example: "logo_image": "[Base64-encoded string representation of GIF, JPEG, or PNG file]"

  - `real_time_stream.player.logo_position` (string)
    The corner of the player in which you want the player logo to appear. The default is top-left.

Example: "logo_position": "top-right"
    Enum: "top-left", "top-right", "bottom-left", "bottom-right"

  - `real_time_stream.player.width` (integer)
    The width, in pixels, of a fixed-size player. The default is 640.

Example: "width": 640

  - `real_time_stream.player_id` (string)
    (Available from version 2.0) The unique alphanumeric string that identifies the player configuration to use for this stream. 
    
    
When you pass a player configuration ID, Wowza Video uses that player configuration to customize and style the player. If you don't pass a value, the default player configuration for the account is used.

Create and edit player configurations in the user interface. The ID is on the General tab for the player configuration.

Default: Default player configuration

Example: 2205b4e8-b160-43c2-868d-d88698a4e850

  - `real_time_stream.hosted_page` (object)
    Configuration of the hosted page.

  - `real_time_stream.hosted_page.title` (string)
    A title for the page that appears above the player. Can't include custom HTML, JavaScript, or other tags.

Example: "title": "My Hosted Page"

  - `real_time_stream.hosted_page.description` (string)
    A description that appears on the hosted page below the player. Can't include custom HTML, JavaScript, or other tags.

Example: "description": "My Hosted Page Description"

  - `real_time_stream.hosted_page.logo_image_url` (string)
    The path to a GIF, JPEG, or PNG logo file that appears in the upper-left corner of the hosted page. Logo file must be 2.5 MB or smaller.

  - `real_time_stream.hosted_page.sharing_icons` (boolean)
    Icons that let viewers share the stream on Facebook, Google+, Twitter, and by email. The default, true, includes sharing icons on the hosted page. Specify false to omit sharing icons.

Example: "sharing_icons": false

## Response 201 fields (application/json):

  - `real_time_stream` (object, required)
    Example: {"id":"2adffc17","name":"MyRealTimeStream","stream_name":"8d304b93f1684320a54f2798666eeca7","token":"97e52731bc21ef66e4c05a8ee1e28b64bf5f9db728573d94e690277cea9215bc","rtmp_url":"rtmp://rtmp-realtime1.wowza.com:1935/v2/pub/8d304b93f1684320a54f2798666eeca7?token=97e52731bc21ef66e4c05a8ee1e28b64bf5f9db728573d94e690277cea9215bc","enable_secure_viewer":false,"state":"started","region":"amsterdam","recording":true,"reference_id":"mySystemID_01","disable_vod_encoder":true,"description":"This is my first real-time stream.","enable_player_and_hosted_page":true,"player_id":"2205b4e8-b160-43c2-868d-d88698a4e850","player_type":"wowza_flowplayer_v2","flowplayer":true,"embed_code":null,"logo_image_url":"https://prod.s3.amazonaws.com/uploads/player/logo_image/23424/5bad28.jpg","logo_position":"top-right","video_poster_image_url":"https://prod.s3.amazonaws.com/uploads/player/video_poster_image/23424/5bad28.jpg","width":640,"hosted_page":{"title":"MyRealTimeStreamHostedPage","url":"https://embed.flowplayer.com/hosted/default/e8dk5bf6","description":"My hosted page description","sharing_icons":true},"created_at":"2021-06-30T18:02:20.000Z","updated_at":"2021-06-30T20:03:16.000Z"}

  - `real_time_stream.created_at` (string)
    The date and time that the real-time stream was created.
    Example: "2021-06-30T18:02:20.000Z"

  - `real_time_stream.id` (string)
    The unique identifier of the real-time stream. Use this ID to perform other operations on the stream, like getting the details of the stream or deleting it.
    Example: "2adffc17"

  - `real_time_stream.name` (string)
    A descriptive name for the real-time stream.
    Example: "MyRealTimeStream"

  - `real_time_stream.stream_name` (string)
    The generated alphanumeric stream name you pass to the SDK.
    Example: "8d304b93f1684320a54f2798666eeca7"

  - `real_time_stream.token` (string)
    The authentication token you pass to the SDK.
    Example: "97e52731bc21ef66e4c05a8ee1e28b64bf5f9db728573d94e690277cea9215bc"

  - `real_time_stream.subscribe_token` (string)
    A secure token that must be passed by viewers for playback. Generated after you set enable_secure_viewer to true.

  - `real_time_stream.rtmp_url` (string)
    The URL you can use to configure an RTMP encoder as the source.
    Example: "rtmp://rtmp-realtime1.wowza.com:1935/v2/pub/8d304b93f1684320a54f2798666eeca7?token=97e52731bc21ef66e4c05a8ee1e28b64bf5f9db728573d94e690277cea9215bc"

  - `real_time_stream.enable_secure_viewer` (boolean)
    Require viewers to pass a security token for playback.

  - `real_time_stream.expires_on` (string)
    The date and time the security token expires. Specify YYYY-MM-DD HH:MM:SS, where HH is a 24-hour clock in UTC. If you don't specify HH:MM:SS, the token expires at 12AM UTC on the specified day. Required when enable_secure_viewer is true.

  - `real_time_stream.state` (string)
    The state of the stream.
    Enum: "started", "stopped", "disabled"

  - `real_time_stream.region` (string)
    An option to set the regional server the stream is distributed through. Select the region closest to your broadcast location for the most reliable stream. If you select the auto option, Wowza Video selects the region based on the publisher's location.

Default: phoenix

Example: "region": amsterdam
    Enum: "phoenix", "amsterdam", "singapore", "bangalore", "auto"

  - `real_time_stream.recording` (boolean)
    If true, records the real-time stream so you can download an MP4 later. The recording starts when the stream starts and stops automatically when the stream stops. 

Recordings for real-time streams capture up to twelve hours of content in a single MP4 file. If the real-time stream recording is longer twelve hours, you'll have multiple files for the recording.

Default: false

Note: You can't update this value after you create the stream.

Example: "recording": true
    Example: true

  - `real_time_stream.reference_id` (string)
    A unique, alphanumeric ID returned in real-time stream webhook payloads. Setting a reference_id is useful if you have an ID in your system or application you want to associate with real-time stream events that trigger webhooks. Maximum 70 characters. Can only contain: a-z A-Z 0-9 !@#$%^&*()-_+=:;,.?~|

You can't use brackets or quotation marks.

See Wowza Video Webhook Event Reference Documentation to learn about webhooks.

Available from version 1.12.

Example: "reference_id": "mySystemID_01"
    Example: "mySystemID_01"

  - `real_time_stream.disable_vod_encoder` (boolean)
    Skips VOD encoding and only creates an MP4 file for download. No VOD stream is created from the real-time stream. 

Can only be set when recording is true and you can't change this value after you create the stream.

Default: false

Example: "disable_vod_encoder": true
    Example: true

  - `real_time_stream.description` (string)
    An optional description of the real-time stream.
    Example: "This is my first real-time stream."

  - `real_time_stream.enable_player_and_hosted_page` (boolean)
    If true, enables a player and hosted page for the real-time stream.

Default: true

Note: You can't update this value after you create the stream.

Example: "enable_player_and_hosted_page": true
    Example: true

  - `real_time_stream.player` (object)
    The player object is deprecated in 2.0. Create and update player configurations in the user interface. 

Any values you send using the player object will be ignored.

The following fields have been moved outside of the player object and reside within the real_time_stream object where you can still access them through the API:
  * embed_code
  * logo_image_url
  * logo_position
  * video_poster_image_url
  * width

  - `real_time_stream.player.id` (string)
    The unique alphanumeric string that identifies the player.

  - `real_time_stream.player.type` (string)
    The player you want to use and the only option is Wowza Flowplayer.

  - `real_time_stream.player.responsive` (boolean)
    A player whose size adjusts according to the device on which it's being viewed. The default value true, creates a responsive player. If specified false, and a player_width is not specified, it defaults to true.

Example: "responsive": true

  - `real_time_stream.player.plugins` (object)
    Configuration of the plugins.

  - `real_time_stream.player.plugins.airplay` (boolean)
    If true, enables Airplay functionality in the player which allows you to cast to an Airplay device. The default is false.

Example: "airplay": false

  - `real_time_stream.player.plugins.chromecast` (boolean)
    If true, enables Chromecast functionality in the player which allows you to cast to a Chromecast device. The default is false.

Example: "chromecast": false

  - `real_time_stream.player.customizations` (object)
    Configuration of the player customizations.

  - `real_time_stream.player.customizations.play_icon` (string)
    A play icon that is displayed on the video preview. The default, solid, uses the standard play (solid triangle) icon. outlined uses an alternate (outlined triangle) play icon. ring uses an alternate (small solid triangle enclosed in a circle) play icon.

        
Default: solid

Example: "play_icon": "solid"
    Enum: "solid", "outlined", "ring"

  - `real_time_stream.player.customizations.thin_timeline` (boolean)
    If true, displays a thinner control bar than the default in the video. The default is false.

Example: "thin_timeline": false

  - `real_time_stream.player.customizations.drag_handle` (boolean)
    If true, displays a drag handle on the progress bar. The default is false.

Example: "drag_handle": false

  - `real_time_stream.player.customizations.volume` (boolean)
    If true, displays a volume button on the video. The default is true.

Example: "volume": true

  - `real_time_stream.player.customizations.mute` (boolean)
    If true, displays a mute button on the video. The default is true.

Example: "mute": true

  - `real_time_stream.player.customizations.fullscreen` (boolean)
    If true, displays a fullscreen button on the video. The default is true.

Example: "fullscreen": true

  - `real_time_stream.player.customizations.show_player_title` (boolean)
    If true, displays a preview title on the video. The default is false.

Example: "show_player_title": false

  - `real_time_stream.player.customizations.color` (string)
    The color of the timeline and volume bar of the player. You can set the color of your choice by passing a hex code for that specific color.

Example: "color": "4d4d4d"

  - `real_time_stream.player.video_poster_image_url` (string)
    The path to a GIF, JPEG, or PNG poster image that appears in the player before the stream begins. Poster image files must be 2.5 MB or smaller.

  - `real_time_stream.player.logo_image_url` (string)
    The path to a GIF, JPEG, or PNG logo file that appears partially transparent in a corner of the player throughout playback. Logo file must be 2.5 MB or smaller.

  - `real_time_stream.player.logo_position` (string)
    The corner of the player in which you want the player logo to appear. The default is top-left.

Example: "logo_position": "top-right"
    Enum: "top-left", "top-right", "bottom-left", "bottom-right"

  - `real_time_stream.player.embed_code` (string)
    The HTML code that can be used in an external webpage to host the Wowza Flowplayer.

  - `real_time_stream.player.width` (integer)
    The width, in pixels, of a fixed-size player. The default is 640.

Example: "width": 640

  - `real_time_stream.player_id` (string)
    (Available from version 2.0) The unique alphanumeric string that identifies the player configuration to use for this stream. 
        
        
When you pass a player configuration ID, Wowza Video uses that player configuration to customize and style the player. If you don't pass a value, the default player configuration for the account is used.

Create and edit player configurations in the user interface. The ID is on the General tab for the player configuration.

Default: Default player configuration

Note: player_id is not returned in the response if it's not explicitly sent and the default player configuration is used instead.

Example: 2205b4e8-b160-43c2-868d-d88698a4e850
    Example: "2205b4e8-b160-43c2-868d-d88698a4e850"

  - `real_time_stream.player_type` (string)
    (Available from version 2.0) The type of player associated with the stream. Streams created in legacy Wowza Video have a  player type of wowza_flowplayer_v1. Streams created in later versions of Wowza Video have a player type of wowza_flowplayer_v2.

Knowing the player type is useful if you've migrated streams from legacy Wowza Video. The player for a stream created in the legacy version of Wowza Video isn't editable in the new platform. 

Example: wowza_flowplayer_v1
    Enum: "wowza_flowplayer_v1", "wowza_flowplayer_v2"

  - `real_time_stream.flowplayer` (boolean)
    Indicates whether or not the player for the live stream is a Wowza Flowplayer player. True indicates the player is a Wowza Flowplayer player. Our new Wowza Video experience uses Wowza Flowplayer. If you are a Wowza Video legacy subscriber, Wowza Flowplayer is also the player used.

False indicates the player is either an original_html5 player or wowza_player. The original HTML and Wowza players are the players available for Wowza Streaming Cloud subscribers.
    Example: true

  - `real_time_stream.hosted_page` (object)
    Configuration of the hosted page.
    Example: {"title":"MyRealTimeStreamHostedPage","url":"https://embed.flowplayer.com/hosted/default/e8dk5bf6","description":"My hosted page description","sharing_icons":true}

  - `real_time_stream.hosted_page.url` (string)
    The URL of the Wowza Video-hosted webpage that viewers can visit to watch the stream.
    Example: "https://embed.flowplayer.com/hosted/default/e8dk5bf6"

  - `real_time_stream.hosted_page.title` (string)
    A title for the page that appears above the player. Can't include custom HTML, JavaScript, or other tags.

Example: "title": "My Hosted Page"
    Example: "MyRealTimeStreamHostedPage"

  - `real_time_stream.hosted_page.description` (string)
    A description that appears on the hosted page below the player. Can't include custom HTML, JavaScript, or other tags.

Example: "description": "My Hosted Page Description"
    Example: "My hosted page description"

  - `real_time_stream.hosted_page.logo_image_url` (string)
    The path to a GIF, JPEG, or PNG logo file that appears in the upper-left corner of the hosted page. Logo file must be 2.5 MB or smaller.

  - `real_time_stream.hosted_page.sharing_icons` (boolean)
    Icons that let viewers share the stream on Facebook, Google+, Twitter, and by email. The default, true, includes sharing icons on the hosted page. Specify false to omit sharing icons.

Example: "sharing_icons": false
    Example: true

  - `real_time_stream.updated_at` (string)
    The date and time the real-time stream was updated.
    Example: "2021-06-30T20:03:16.000Z"

## Response 401 fields (application/json):

  - `meta` (object, required)

  - `meta.status` (integer)

  - `meta.code` (string)

  - `meta.title` (string)

  - `meta.message` (string)

  - `meta.description` (string)

  - `meta.links` (array)

## Response 422 fields (application/json):

  - `meta` (object, required)

  - `meta.status` (integer)

  - `meta.code` (string)

  - `meta.title` (string)

  - `meta.message` (string)

  - `meta.description` (string)

  - `meta.links` (array)