Multi-Type Scoreboard Insertion Guide

This guide provides comprehensive instructions for seamlessly integrating professional scoreboard functionality into your sports broadcasts. We offer two modes: the HTML Web View (html) for superior visual experience and the Video Stream Overlay (stream) for operational convenience.

Prerequisites

Before proceeding, ensure you have the following ready:

Valid API Key (for Basic Authentication).
Python 3.x Environment and the requests library.
Content Source Preparation:
- type=html: An accessible HTML Scoreboard URL (must have a transparent background).
- type=stream: A separate, dedicated Scoreboard Video Stream source (e.g., a secondary RTMP feed).

API Reference

Action	HTTP Method	Endpoint	Purpose & Key Constraint
1. Initialize Scoreboard	`POST`	`/live/v1/live-streams`	Initial Configuration: Configures the scoreboard's type, source, and initial style upon stream creation. Docs：Initialize Scoreboard
2. Update Scoreboard	`PUT`	`/live/v1/live-streams/{stream-id}/generated-watermark`	Used for real-time adjustments to the content source and/or visual settings. Docs:Update Scoreboard
3. Delete Scoreboard	`DELETE`	`/live/v1/live-streams/{stream-id}/generated-watermark`	Removes the scoreboard feature. Docs:Delete Scoreboard

Critical State Dependency Warning

⚠️ IMPORTANT: Visual settings (such as overlay_settings for position, size, and opacity) can only be configured and take effect when the stream is in the idle state. To adjust these settings, you must stop the stream, update the configuration, and then restart the broadcast.

Configuration Details by Scoreboard Type

The API response for POST /live/v1/live-streams contains two main groups of fields: Main Stream Information (at the root data level) and nested generate_watermark Scoreboard Configuration.

API Response Common Fields (Main Stream Root)

The root data object returns essential information for your primary broadcast stream:

Field Name	Description
`id`	Main Stream ID, required for all subsequent API calls.
`stream_key`	Primary Stream Key, used for pushing the main video content.
`status`	The current state of the live stream (`idle`, `active`, `disable`, etc.).
`playback_ids`	Playback IDs for viewer access.

Type 1: HTML Web View (`type: "html"`)

Request Parameters (for `generate_watermark`)

Parameter Name	Type	Required	Description
`type`	String	Yes	Must be `"html"`.
`url`	String	Yes	HTML Source: The URL of the transparent HTML scoreboard page.
`page_load_timeout`	Integer	No	Timeout in seconds for loading the HTML page.
`overlay_settings`	Object	No	Visual positioning and sizing configuration.

`generate_watermark` Response Fields

Field Name	Description
`type`	`"html"`
`url`	The configured scoreboard URL.
`page_load_timeout`	The configured timeout value.

Type 2: Video Stream Overlay (`type: "stream"`)

Request Parameters (for `generate_watermark`)

Parameter Name	Type	Required	Description
`type`	String	Yes	Must be `"stream"`.
`audio_mix_settings`	Object	Yes	Audio Mixing Configuration: Controls volume levels for the main and secondary stream audio.
`overlay_settings`	Object	No	Visual positioning and sizing configuration.

`generate_watermark` Response Fields

Field Name	Description
`type`	`"stream"`
`stream_key`	Critical: The unique push key for the scoreboard video content.
`stream_url`	Critical: The RTMP push URL where the scoreboard video feed must be sent.
`audio_mix_settings`	The configured audio mixing settings.

Usage Instructions: Scoreboard Push Credentials

Crucial Note: When type is "stream", the stream_key and stream_url in the response are dedicated to the scoreboard video stream. You must use these credentials with a separate encoder/software to push the scoreboard content. The main broadcast stream still requires the stream_key from the response root.
Push Timing Constraint: There must be a delay between starting the main live stream and the scoreboard stream. This gap must be no less than 10 seconds

Complete Code Examples (Python)

Example A: Create Stream with HTML Type Scoreboard

import requests
import json

url = "https://api.visionular.com/live/v1/live-streams"
html_scoreboard_url = "https://my-custom-graphics.com/scoreboard/game123.html"

payload_html = {
    "policy": ["public"],
    "latency_mode": "standard",
    "generate_watermark": {
        "type": "html",
        "url": html_scoreboard_url, 
        "overlay_settings": {
            "width": "60%",
            "vertical_align": "bottom",
            "horizontal_align": "center",
            "opacity": "95%"
        },
        "page_load_timeout": 5 
    },
    "record": False
}

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_AUTH' 
}

print("--- Creating Stream with HTML Scoreboard ---")
response = requests.post(url, headers=headers, json=payload_html)
print(json.dumps(response.json(), indent=4))

Example B: Create Stream with Stream Type Scoreboard

import requests
import json

url = "https://api.visionular.com/live/v1/live-streams"

payload_stream = {
    "policy": ["public"],
    "latency_mode": "standard",
    "generate_watermark": {
        "type": "stream",
        "overlay_settings": {
            "width": "35%",
            "height": "35%",
            "vertical_align": "top",
            "horizontal_align": "right",
            "opacity": "100%"
        },
        "audio_mix_settings": {
            "mode": "main", 
            "volume_main": 1,
            "volume_secondary": 0 # Mute the secondary stream audio
        }
    },
    "record": True
}

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_AUTH' 
}

print("\n--- Creating Stream with Stream (PIP) Scoreboard ---")
response = requests.post(url, headers=headers, json=payload_stream)
response_data = response.json()
print(json.dumps(response_data, indent=4))

# --- Extracting Critical Credentials ---
if response_data.get('data'):
    main_stream_key = response_data['data']['stream_key']
    scoreboard_config = response_data['data']['generate_watermark']
    scoreboard_stream_key = scoreboard_config['stream_key']
    scoreboard_stream_url = scoreboard_config['stream_url']
    
    print(f"\n✅ Main Video Push KEY: {main_stream_key}")
    print(f"✅ Scoreboard Push KEY: {scoreboard_stream_key}")
    print(f"✅ Scoreboard Push URL: {scoreboard_stream_url}")
    print("\n❗ Remember: Start the two pushers 10 seconds apart.")

Visionular