Uiza Documentation
2022-06-06
2022-06-06
  • Hola! 👋
  • Getting Started
    • Introduction
    • Authentication
    • Errors
    • Quick Starts
      • Live Streaming
      • Video Streaming
    • Pagination
    • Recommended Specifications
    • Sample Streaming Apps
      • NodeJS Live Streaming App
      • Java Live Streaming App
      • Python Live Streaming App
      • How to integrate live streaming into an Android App using Uiza’s Live API
    • Versioning
  • API Reference
    • Live Entities
      • Create a live entity
      • Retrieve a live entity
      • Update a live entity
      • Delete a live entity
      • List all live entities
      • Create a live relay
      • Update a live relay
      • Delete a live relay
    • Video Entities
      • Create a video entity
      • Retrieve a video entity
      • Update a video entity
      • Delete a video entity
      • List all video entities
    • Events
      • Event Types
    • Webhook Endpoints
      • Verifying signatures
      • Create a webhook endpoint
      • Update a webhook endpoint
      • Get a webhook endpoint
      • List all webhook endpoint
  • SDK REFERENCE
    • Introduction
    • Android SDK
      • Android Player SDK
      • Android Broadcast SDK
    • iOS SDK
      • iOS Player SDK
      • iOS Broadcast SDK
    • Web Player SDK
    • Flutter SDK
  • API UPGRADES
    • Release Notes
    • API Changelog
Powered by GitBook
On this page
  • Step 1: Create a live entity
  • /v1/live_entities
  • Step 2: Retrieve a live entity
  • /v1/live_entities/:id
  • Step 3: Configure your broadcasting software and start broadcasting
  • Step 4: Configure the playback link to your player and start watching your live stream!

Was this helpful?

  1. Getting Started
  2. Quick Starts

Live Streaming

PreviousQuick StartsNextVideo Streaming

Last updated 2 years ago

Was this helpful?

Our REST APIs use standard HTTP response codes, authentication, and verbs, and return JSON-encoded responses. Using these APIs, you will be able to start a live event and stream the content to our network, which will deliver that content to your audiences. Once a live entity is created, Uiza allocates dedicated resources and return an RTMP server to ingest and deliver your stream. The overall framework is articulated in the diagram below.

Step 1: Create a live entity

/v1/live_entities

POST https://api.uiza.sh/v1/live_entities

Request Body

Name
Type
Description

name

string

The name of your live entity.

region

string

Choose the region closest to the location of your streamer.

description

string

The description of your live entity (maximum is 1000 characters)

dvr

boolean

Indicates whether Digital Video Record (DVR) is enabled for the live_entity. Set as true to enable and as false to disable. The default value is false.

encode

boolean

Indicates whether encoding mode is enabled for the live_entity. Set as true to enable and as false to disable. The default value is false, when the encode is true, it required a preset_id.

preset_id

string

The identifier of the video_preset to be applied when encoding your signal.

relay

array

A list of ingest servers to be relayed. Contains url and key and name (optional) in each ingest server.


  "id": "2b970a39-874a-4d2a-be8a-fd445646d74c",
  "name": "Test event without encoding",
  "description": "Event for Test",
  "region": "in-bangalore-1",
  "status": "init",
  "dvr": false,
  "encode": false,
  "ingest": null,
  "playback": null,
  "relay": [
    {
      "url": "rtmp://youtu.be/live",
      "key": "Abco1",
      "name": "Youtube 1"
    }
  ],
  "preset": null,
  "created_at": "2020-03-23T07:22:34Z",
  "updated_at": "2020-03-23T07:22:34Z"
}
{
    "id": "b7f02d48-d0ec-4c34-86d1-247a38eda4e1",
    "name": "Test event with encoding",
    "description": "Event for Test",
    "ingest": null,
    "playback": null,
    "relay": [
        {
            "url": "rtmp://youtu.be/live",
            "key": "Abco1",
            "name": "Youtube 1"
        }
    ],
    "region": "in-bangalore-1",
    "status": "init",
    "dvr": false,
    "encode": true,
    "preset": {
        "id": "9432fa62-5988-11ea-883b-028fc5698662",
        "name": "Uiza LIVE 720p",
        "description": "",
        "is_default": true,
        "profiles": [
            {
                "id": "85844e8b-6281-11ea-883b-028fc5698662",
                "name": "720p H264 30fps Normal Latency",
                "segment_duration": 4,
                "orientation": "landscape",
                "video_profile": {
                    "video_resolution": "720",
                    "video_codec": "H264",
                    "video_bitrate": "2000K",
                    "video_frame_rate": "30"
                },
                "audio_profile": {
                    "audio_channel": "2",
                    "audio_codec": "AAC",
                    "audio_bitrate": "128K",
                    "audio_frame_rate": "1"
                }
            }
        ],
        "created_at": "2020-02-27T17:42:52Z",
        "updated_at": "2020-02-29T16:47:34Z"
    },
    "created_at": "2020-03-23T07:22:34Z",
    "updated_at": "2020-03-23T07:22:34Z"
}
Sample Request
curl -X POST https://api.uiza.sh/v1/live_entities \
-H 'Authorization: uap-c1ffbff4db954ddcb050c6af0b43ba56-41193b64' \
-d '{"name": "Test Event", "region": "in-bangalore-1", "description": "Test 1"}'

Please pay attention that you entered a supported region, else the API will return an error message. Defining correct region helps Uiza allocates the resource that is closest to the streamer location. This will minimize the risks of network issues and reduce the impact on your business. While we are adding more and more regions to Uiza Network, please check the current available regions below:

in-bangalore-1 (Bangalore - India)

in-mumbai-1 (Mumbai - India)

sg-singapore-1(Singapore)

vn-saigon-1 (Vietnam)

Step 2: Retrieve a live entity

You will need the ingest.key and ingest.url to configure your broadcasting software. These 2 attributes could be retrieved by using the id you get in the response in Step 1 for the Retrieve an entity API.

It is important that the value of the status you get from the response is ready, meaning that resources have been allocated and ready to ingest and broadcast your live feed. If the status of your entity is init, meaning that Uiza is still allocating resources for your entity and your live signal will not be able to be ingested and broadcasted during this process. Please, be patient and keep requesting for the entity's information until you get the ready status. This process may take up to 1 minute.

/v1/live_entities/:id

GET https://api.uiza.sh/v1/live_entities/:id

Path Parameters

Name
Type
Description

id

string

The unique identifier of a live entity to be retrieved information

{
 "id": "2b970a39-874a-4d2a-be8a-fd445646d74c",
 "name": "Test Event",
 "description": "Test 1",
 "ingest": {
   "url": "rtmp://f45dd07a0e-in.uizadev.io/transcode",
   "key": "live_TB62vHgxSY"
 },
 "playback": {
   "hls": "https://f45dd07a0e.uizadev.io/fmp4/22013d8a-d5fa-48f0-9a63-1f471ca9e81d/master.m3u8"
 },
 "region": "in-bangalore-1",
 "status": "ready",
 "dvr": false,
 "broadcast": "offline",
 "created_at": "2019-12-11T02:47:04Z",
 "updated_at": "2019-12-16T02:53:30Z"
}
Sample Request
curl -X GET https://api.uiza.sh/v1/live_entities/2b970a39-874a-4d2a-be8a-fd445646d74c \
-H 'Authorization: uap-c1ffbff4db954ddcb050c6af0b43ba56-41193b64' 

Step 3: Configure your broadcasting software and start broadcasting

Once you have configured the ingest.url and ingest.key, you could start streaming right away.

Step 4: Configure the playback link to your player and start watching your live stream!

The playback links (hls for HLS streaming and mpd for MPEG-dash streaming) of your live entity is the value of playback returned in Step 2. With the HLS link obtained, you could play your live stream by these methods:

  1. Configure the HLS link to Player SDK.

  2. Paste the HLS link to Safari and play directly with Apple's native player.

  3. Install the HLS extension and play it on Google Chrome browser.

To start streaming, you need a to be created with resources allocated, ready to broadcast the live signal. You could create a live entity by using Create A Live Entity API.

You could also set up a to be notified automatically when your live_entity is ready.

Most available broadcasting software uses which requires a server's URL and a Stream Key to direct the live signal to the ingest servers. Use the ingest.url and ingest.key obtained at Step 2 to configure your broadcasting software in their Settings. The following are the 2 most popular broadcasting software that we strongly recommend.

OBS Studio (Available for Mac, Windows, and Linux) - Get it .

Streamlabs (The best live streaming app for iPhone & Android) - Get it .

The mpd video format could be played natively by .

By following these 4 steps, you will be able to live stream your event using Uiza. We understand that this beta version of ours requires quite some amount of manual involvement, but we are working hard to deliver a more delightful experience with more APIs and automation. If you are ready to live-stream your first event, let's move on to the API Reference.

🙏
live_entity
webhook
RTMP protocol
here
here
Microsoft Edge