Skip to main content

VSR Studio Manual

VSR Studio is an application for controlling an Eyeson Virtual Situation Room. It manages video sources and scenes and starts an Eyeson room from permalink credentials. In the current version, VSR Studio is embedded in the VSR Studio Service executable.

VSR Studio needs two credentials from an Eyeson permalink:

  • The User Token (user_token) allows VSR Studio to start and control the room. Keep it private.
  • The Guest Token (guest_token) allows guests and VSR Studio Service to connect to the room. The corresponding guest link may be shared with participants.

If your organisation manages Eyeson, ask your administrator for both tokens and the correct API Endpoint, then continue with Installation, setup, and configuration.

Eyeson Cloud​

If you manage an Eyeson Cloud account yourself:

  1. Sign in to the Eyeson API dashboard and obtain an API key. Keep the API key secret.

  2. Create a permalink by sending the following request. Replace YOUR_API_KEY, host-user-id, and Host Name with your own values:

    curl -X POST \
      -H "Authorization: YOUR_API_KEY" \
      -d "user[id]=host-user-id" \
      -d "user[name]=Host Name" \
      -d "options[sfu_mode]=disabled" \
      -d "options[widescreen]=true" \
      "https://api.eyeson.team/permalink"

    The permalink's widescreen option must be enabled because VSR Studio scenes use a 1280 × 720 layout.

  3. In the JSON response, find the permalink section:

    {
      "permalink": {
        "user_token": "<24-character user token>",
        "guest_token": "<24-character guest token>"
      }
    }

On-premises Eyeson​

For an on-premises deployment, do not use the public dashboard or https://api.eyeson.team unless your administrator explicitly tells you to do so.

  1. Ask your Eyeson administrator for the organisation's API endpoint and a permalink user token and guest token.
  2. If you are authorised to create the permalink yourself, send the same POST /permalink request shown above to your on-premises API endpoint instead of https://api.eyeson.team. Use the API key issued for that deployment.
  3. Enable options[widescreen]=true and copy permalink.user_token and permalink.guest_token from the response.

Ask your administrator for deployment-specific network and access details. See Eyeson deployment options.

Save the credentials​

  1. Copy user_token into User Token and guest_token into Guest Token in VSR Studio's Global Settings.
  2. Store both tokens securely. Do not share the user token or the host GUI link: either can start the room. Share only the guest link when inviting participants.

For all request options and response fields, see the official Eyeson Permalink documentation.

warning

The Eyeson API key is only used to create or manage the permalink. Do not paste it into the User Token or Guest Token fields.

2. Installation, setup, and configuration​

Requirements​

Before starting, make sure you have:

  • A VSR Studio Service executable supplied directly by Eyeson for your operating system and processor architecture.
  • Eyeson host and guest tokens supplied by your administrator. Both tokens must be 24 alphanumeric characters.
  • For Eyeson Cloud: access to the Eyeson API.
  • For on-premises Eyeson: network access to the API supplied by your administrator.
  • When the browser and VSR Studio Service run on different computers: network access from the browser to the service address and port.
  • Network access to all RTSP or playback source URLs you plan to use.

Install and open VSR Studio​

Supplied by Eyeson

VSR Studio Service is not currently available as a public download. These instructions assume that Eyeson has supplied the correct executable for your system.

  1. Check that the supplied executable matches your system:

    • Windows: ghost-server-windows-amd64.exe
    • macOS with Apple Silicon: ghost-server-darwin-arm64
    • macOS with an Intel processor: ghost-server-darwin-amd64
    • Linux: ghost-server-linux-amd64 or ghost-server-linux-arm64

  2. On macOS or Linux, make the supplied file executable once. Replace the filename with the file you received:

    chmod +x ./ghost-server-darwin-arm64

  3. Start VSR Studio Service:

    • On Windows, macOS or Linux, run the matching executable from a terminal, for example:

      ghost-server-windows-amd64.exe or ./ghost-server-darwin-arm64

  4. If your operating system asks for network or firewall access, allow it.

  5. Open a web browser and go to http://127.0.0.1:4455.

Port 4455 is used per default but can be changed using -rest-addr ipaddress:port. Running the executable automatically starts VSR Studio Service's local database, REST service, RTMP service, and embedded VSR Studio interface with their default settings. It does not currently open the browser automatically. Keep the terminal or VSR Studio Service process running while preparing sources and scenes or using a live session.

Access VSR Studio from another computer​

VSR Studio Service and the browser can run on different computers. Start the service with an address that the browser computer can reach:

<SERVICE_EXECUTABLE> -tls -rest-addr <SERVICE_HOST>:4455

Replace the placeholders with the supplied executable and the service computer's hostname or IP address. Then open https://<SERVICE_HOST>:4455 in the browser. Ask your administrator if the address or port is unavailable.

warning

The browser may display a certificate warning on the first connection. Verify the address with your administrator before proceeding.

Configure Global Settings​

The Virtual Situation Room Configuration dialog opens automatically on first launch. Later, open it with Global Settings at the bottom of the side panel.

On the Setup tab, enter:

  • API Endpoint: use https://api.eyeson.team for Eyeson Cloud. For on-premises Eyeson, enter the API base URL supplied by your administrator.
  • Service Address: the address of the running VSR Studio Service. When VSR Studio is opened at the default local address, this should be http://127.0.0.1:4455. In a separated setup, it should match the reachable service URL, such as https://vsr-service.example:4455. The field is normally filled automatically from the address used to open VSR Studio; the reset button restores the current application address.
  • User Token: enter the permalink user_token created on the same Cloud or on-premises Eyeson system as the API Endpoint.
  • Guest Token: enter the matching permalink guest_token.

On the Customisations tab you may select the light or dark theme, language, and optional custom branding (accent colour and logo).

Select Apply to validate and save the settings. They remain stored on this computer for the next launch.

3. Prepare sources and scenes​

Prepare all sources and scenes before the Eyeson session is running. The VSR Studio Service executable must still be running, and the computer must be able to reach a source if you want to test that source. No Eyeson session is started and no room usage is consumed during preparation.

If the computer has no external internet connection, local source and scene definitions can still be prepared through VSR Studio Service. Cloud rooms cannot be started until internet access returns. In an on-premises environment, a live session only requires access to the organisation's internal Eyeson services and media networks, according to the local deployment configuration.

Create and check sources​

Sources are reusable video inputs managed by VSR Studio Service. Open the Sources section in the left panel and select New source.

  1. Enter a Display Name.
  2. Check the generated Unique ID. IDs must be unique; an existing ID is automatically replaced with a generated one.
  3. Choose a Protocol and Type:
    • rtsp: choose ip-cam or drone, then enter the RTSP URL.
    • rtmp: choose drone or ip-cam. VSR Studio provides the RTMP ingest URL after creation.
    • playback: video playback from a WEBM or MP4 URL. Enable Loop to repeat it and Audio to include its audio.
  4. Select Add Source.
  5. To test an available source, use its visibility button to activate it and wait for Connected, Activated, or Playing.... Deactivate it again after the test if it should not start with the session.

An active source must be deactivated before it can be edited. You can create source definitions even when the source device is unavailable, but its connection cannot be verified until the device and network are available.

Create scenes​

Scenes store a source arrangement and optional visual layers. They can be created and edited without starting a room. Open Scenes and select New scene.

  1. Enter a scene name.
  2. Choose a scene type:
    • Auto arranges active sources automatically.
    • System uses a built-in preset.
    • Template starts from a saved layout and allows position adjustments.
    • Custom starts with an empty layout for freely placed and sized positions.
  3. Complete the tabs shown for the selected type:
    • Sources: choose the sources included in an Auto scene.
    • Layout: select a system layout or template.
    • Mapping: add or remove positions and set their coordinates, size, and object fit. Keep all positions inside the 1280 × 720 area.
    • Positions: drag available sources onto layout positions.
    • Layers: optionally add a background or overlay by URL or file. Supported formats are PNG, WebP, and JPEG. Backgrounds are centred and scaled; overlays are placed from the top-left and are not scaled.
    • Other Options: configure automatic placement, participant names, and voice activation when available for the selected scene type.
  4. Select Create Scene.

Before the live session, create the scenes you expect to use, check that every scene references the correct source IDs, and prepare local background/overlay files. A scene with a deleted or unavailable source shows Missing sources; edit it and reassign the source before going live.

Back up the preparation​

Use the Import / Export button beside Global Settings to export sources and scenes as JSON. Keep this file as a backup or import it on another prepared VSR Studio computer. During import, items whose IDs already exist are skipped.

4. Use VSR Studio during a live session​

Start the session​

  1. Confirm that the VSR Studio Service executable is still running and that the Global Settings are correct.
  2. Confirm that all required source devices and networks are available.
  3. Click Start VSR in the main area.
  4. VSR Studio starts the Eyeson room with the user token, configures guest access, and displays the room in the application window.
  5. Wait until the room is ready. Use the QR-code button to display the guest join link or share the guest link from within the VSR.

For scene layouts, the Eyeson permalink must have the widescreen option enabled. VSR Studio warns when the room resolution is not widescreen because scenes are designed for a 1280 × 720 layout area.

Operate sources and scenes​

  1. In Sources, activate each input required for the session and wait for a healthy status.
  2. In Scenes, select the scene you want to show. It is applied automatically when the room is ready.
  3. Change scenes by selecting another scene in the list.
  4. Use the focus button beside a source to temporarily show that source prominently. Select it again to return to the previously selected scene. A focused source cannot be deactivated.
  5. Monitor the source status labels. If a required source reports an error, verify the device/network, then deactivate and reactivate it.

You can edit a scene during the session. When the currently selected scene is saved, VSR Studio reapplies it automatically. Avoid changing source IDs or deleting sources during a live session. Scenes with missing sources can be applied, but those inputs will not appear.

End the session​

  1. Select End VSR.
  2. VSR Studio ends the Eyeson room and deactivates forwarding. The prepared sources and scenes remain available for the next session.

5. References​

6. Troubleshooting​

Start Session is disabled​

VSR Studio Service may not be ready or may have stopped. Stop and restart the VSR Studio Service executable, reload http://127.0.0.1:4455, and try again. If the problem remains, open Global Settings, reset Service Address to the current application address, and select Apply. Contact your administrator if the session is still unavailable.

The host or guest token is rejected​

Use the permalink values returned as user_token and guest_token, not a room URL or API key. Each token must contain exactly 24 letters and numbers. Remove spaces before or after the value.

The room does not start​

Verify the API endpoint and user token, confirm that the computer can reach the configured Cloud or on-premises Eyeson service, and check whether the permalink is still valid. If the problem continues, contact your administrator or support team with the error message displayed by VSR Studio.

A source stays on Connecting or shows an error​

Confirm that the source device is online and that its URL, credentials, protocol, media format, and port are correct. Deactivate the source, edit it, and activate it again. Playback supports WEBM and MP4.

I cannot edit or deactivate a source​

Deactivate an active source before editing it. If the source is focused, unfocus it first; focused sources cannot be deactivated.

A scene cannot be created​

Complete the current step before continuing: provide a scene name, select a layout where required, add at least one position, and assign at least one source. Fix invalid layer URLs or reselect a missing local layer file.

A scene is incomplete or reports missing sources​

Activate and connect the required sources, or edit the scene and remove/reassign missing source IDs. Imported scenes do not automatically recreate items when the same IDs already exist.

The layout looks wrong or a widescreen warning appears​

Enable the Eyeson permalink's widescreen option. Scene coordinates target 1280 × 720; custom positions outside that area may be clipped. Also verify that the overlay resolution does not exceed the room resolution.

Settings or layouts are stale​

Use Global Settings → Clear Storage (dev) only when instructed by your administrator or support team. It removes local settings, cached layouts, and sorting preferences, then restarts the application. Export anything you need before using it.

Camera, microphone, or the room window does not work​

Allow camera, microphone, and network access when requested by the browser or your operating system. Close other applications that may be using the camera or microphone, restart the VSR Studio Service executable, and reload VSR Studio. If the room still does not load, check your network and firewall or contact your administrator.