LogoLogo
API Status
  • 👋Welcome
  • 🌐What is Morpheus Platform?
    • Interoperability
  • â„šī¸Help
    • 📗Glossary
    • 🆘Support
    • Firewall problems
    • EULA
  • CREATION
    • 🎮Unreal Development
      • ⚡Get Started
        • âš’ī¸Download the Editor
        • âĢUpload Content
        • 🌎Creating your own map
        • 📝Morpheus Base Project
        • ❓Differences from Unreal
          • 🧍Character Configuration
        • 📡Morpheus Networking
          • Introduction to Morpheus Networking
          • Network Levels
          • Replicated Properties
          • RPCs
          • Morpheus Render Targets
          • Morpheus Array
          • Networking FAQ
          • Replicating Sublevels
      • 📚Features & Guides
        • 📒Example Plugin
          • Nameplates
          • In-game roles
        • 🏊Actor Pooling
        • 🔊Audio
        • 🎭Avatars
          • Creating an Avatar
          • Attachments
            • MML Attachments
          • Custom Animation Variables
          • Importing an NFT collection
          • Capsules and Mesh Transforms
        • 🤖Bots
        • đŸŽ™ī¸Chat
          • Unreal Text Chat
        • đŸŽ›ī¸Control Panels
          • Control Panel Configuration
          • DJ booth mission control
          • Observer Controls
        • 🔉Crowd Audio
        • đŸ¤ŧCrowd Rendering
          • Legacy Animated Crowd
            • Animated Crowd Console Commands
            • Attaching static meshes to crowd members
          • Crowd Materials
          • Performance Parameters
          • Live Config Settings
          • Crowd Animation
            • Crowd Anim Blueprint
              • User Guide - Crowd Anim Blueprint
              • Reference Guide - ABP Nodes
                • Animation Playback
                • States and State Machines
                • Variables
                • Transitions
                • Special
                • Blends
                • Additional Notes
        • 🍱Helpers & Extras
          • "Instanced Objects" in Blueprints
          • Objects with "world context"
          • Making DataAsset classes
          • Duplicate Objects
          • The Bootflow Subsystem
          • The "Wait For Condition" System
          • Advanced Graphics settings
          • Listening to inputs on UObjects
          • Morpheus UserID
          • World Services
          • M2Extras: Skins System
        • đŸ–Ĩī¸Loading Screen
        • ⚡Live Config
          • Editing for a World
          • Editing Locally
          • Default Settings
          • Accessing via Blueprint
          • Adding New Settings
          • Overriding Defaults
          • Using Arrays
        • 🧊MML
        • đŸ•ēMotion Capture
        • 📡Networking
        • đŸ“ĸNotifications
        • Raycastable Crowd
        • 🌐Singletons
        • 📱Streaming & Multiplatform
          • GFN on mobile
        • đŸ–Ĩī¸UI
          • "UI Mode"
        • đŸ—ƒī¸User Collections
          • Creating a New Object Definition
          • Accessing from Unreal
            • Creating Objects Definitions
            • Transfer Objects
            • User Collection Views
            • Receiving Updates
        • đŸ“ēVideo Players
          • Embedded Video Player
          • Millicast video streaming
            • How to Setup an In-Game Video Stream
            • Picture-in-Picture mode
          • Streaming Video Player
            • How to Setup a URL Video Player
            • Picture-in-Picture mode
        • 🐞Visual Debugging
          • Inspector
        • đŸĒŸWeb UI
        • 💠Web Requests
          • Http Requests
            • Legacy HTTP Nodes
          • JSON Handling
          • WebSockets
          • Identity Validation
          • Allowed External URLs
          • Walkthrough Example
            • Example Counter Service
        • âœˆī¸World Travel
          • World Travel in the editor
        • Avatar Physics Assets
        • Action Gameplay Helper Components
      • 🔑Workflows
        • â†—ī¸Upgrade the Editor
          • đŸ–Ĩī¸Version History
        • âš™ī¸Editing Project Settings
        • 📈Profiling
        • đŸ§ēMarketplace Importing
        • đŸ› ī¸Extra Workflows
          • Setup Play-in-Editor
          • Setup Local Asset Validation
          • Adding Gameplay Tags
          • Validating Game Assets
          • Custom Connection Modes
          • Connect Editor to a World
          • Common Issues
      • 📚Useful Reading
        • ⭐Best Practices
    • 🌎Worlds
      • 📩Invite Players
        • Setting Role Groups
      • Persistent Worlds
      • Always on Worlds
    • 📅Running events
      • ✅Large scale events - Checklist
      • 👾Anti-Cheat (EAC)
      • 🎮Player Entry
        • 📱React Native
        • Steam
        • đŸ’ģHardware Reqs
      • đŸŽĨBroadcast
        • 📹OBS Integration
      • Failover
      • 🏁Capacity And Queue Management
  • ADMINS
    • đŸ‘ĒAccess Control
      • Adding metaverse contributors
      • Creating a new project
    • 💲Pricing
      • Development Support
      • Included Usage & Overages
      • Cloud Streaming
      • Access Modes
      • War Room Support
      • Platform SLA
    • âš™ī¸Settings
      • đŸ—ƒī¸Projects
  • APIs and Tooling
    • đŸ–Ĩī¸API Reference
      • Accounts
      • Events
      • Key/Value Store
      • Organizations
      • Realtime
      • User Profile
      • World Builder
      • Worlds
    • Pixel Streaming
    • 🚀Launcher
  • Integrations
    • 📊Analytics
      • Sending events from web
      • 🎮Sending Events from Unreal
    • đŸ’ŦChat
      • 🎮Integrating Pubnub with your Unreal Project
      • Adding Moderation to Chat
Powered by GitBook
On this page
  • Installation
  • Usage
  • Obtaining an Auth Token
  • Granting streaming permissions for your world
  • React
  • Aspect Ratio Support
  • Supported Aspect Ratios

Was this helpful?

  1. APIs and Tooling

Pixel Streaming

Pixel Streaming allows a high-fidelity interactive experience to be streamed directly to users' device, regardless of its graphical capabilities.

PreviousWorldsNextLauncher

Last updated 2 months ago

Was this helpful?

We provide a for viewing pixel-streamed content from MSquared events.

Installation

When bundling with a modern build tool, you can install the package directly from npm:

npm install @msquared/pixel-streaming-client

This package provides ESM, CJS and UMD modules.

Alteratively, you can include the following script and use the client directly in the browser via window.MSquaredPixelStreamingClient:

<script src="https://cdn.jsdelivr.net/npm/@msquared/pixel-streaming-client@latest/dist/script/index.js"></script>

Usage

import { StreamingClient, StreamProvider, StreamTarget } from '@msquared/pixel-streaming-client';

// Initialize client
const client = new StreamingClient({
  auth: {
    // See "How to obtain an auth token"
    token: 'your-auth-token',
    organizationId: 'your-org-id'
  },
  logger: console
});

// Listen for state changes
client.addEventListener('streamStateUpdated', (event) => {
  console.log('Stream state:', event.detail.state);
});

// Fetch stream configuration
const config = await client.fetchStreamConfig({
  projectId: 'your-project-id',
  worldId: 'your-world-id',
  forceProvider: StreamProvider.GeforceNow,
});

// Start an embedded stream
await client.start({
    ...config,
  provider: StreamProvider.GeforceNow,
  target: StreamTarget.Embedded,
  container: '#stream-container',
});

Obtaining an Auth Token

To use the Pixel Streaming Client, an MSquared ID token is required.

If you need a temporary or throwaway account, you can generate one programmatically.

This must be done on your web server, as the API key is a secret and should never be exposed in your web client.

Below is a reference script for generating accounts using the MSquared API:

const apiKey = "..." // Speak to MSquared to obtain an API key
const organizationId = "..." // Your organization ID - shown on the MSquared dashboard
const userId = randomUUID() // Must be a unique per session
const displayName = "..." // The display name you want to display for the user's avatar
const yourDomain = "example.com" // Can be whatever value you want

const userResp = await fetch(
  `https://${organizationId}.m2worlds.io/api/accounts/auth/user/`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": apiKey,
    },
    body: JSON.stringify({
      email: `${userId}@${yourDomain}`,
      emailVerified: true,
      displayName: displayName,
    }),
  },
)
const user = await userResp.json()

const tokenResp = await fetch(
    `https://${organizationId}.m2worlds.io/api/accounts/token/generate`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": apiKey,
        },
        body: JSON.stringify({
            userId: user.uid,
        }),
    },
)
const token = await tokenResp.json()

const signinResp = await fetch(
    `https://${organizationId}.m2worlds.io/api/accounts/token/signin`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": apiKey,
        },
        body: JSON.stringify({
            token: token.token,
        }),
    },
)
const signin = await signinResp.json()

// Users must have a username set, or they will be unable to enter a world
await fetch(`https://${organizationId}.m2worlds.io/api/profile`, {
    method: "PUT",
    headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${authToken}`,
    },
    body: JSON.stringify({
        username: displayName,
    }),
})
    
// The auth token needed to start a streaming session
const authToken = signin.idToken

Granting streaming permissions for your world

You will need to grant permission for users to stream your world.

If you are creating temporary/throwaway users (as described above) you can do the following:

  1. Go to https://your-organisation.msquared.io/dashboard/admin/access

  2. Create a new role with the following properties:

    1. Group name: Public Access

    2. Members:

      1. Type: Email Domain

      2. Enter the same domain you used to generate temporary accounts

    3. Access type:

      1. Type: World Access

      2. Select all projects you want these users to access

React

The usePixelStreaming hook provides an easy way to integrate pixel streaming in React:

"use client"

import { useRef, useState, useCallback, useEffect } from "react"
import { usePixelStreaming } from "@msquared/pixel-streaming-client"

type Params = {
    organizationId: string
    projectId: string
    worldId: string
    authToken: string
}

export function PixelStreamingClient({ organizationId, projectId, worldId, authToken }: Params) {
    const [started, setStarted] = useState(false)
    const streamContainerRef = useRef<HTMLDivElement | null>(null)
    const { startStreaming, stopStreaming } = usePixelStreaming({
        organizationId,
        projectId,
        worldId,
        authToken,
    })

    const start = useCallback(() => {
        if (started || !streamContainerRef.current) return
        setStarted(true)
        startStreaming({ ref: streamContainerRef.current })
    }, [started, startStreaming])

    useEffect(() => {
        return () => stopStreaming()
    }, [stopStreaming])

    return (
        <div className="h-screen w-full bg-black relative">
            <div className="absolute inset-0" ref={streamContainerRef} />
            {!started && (
                <button onClick={start} className="absolute bottom-8 left-1/2 transform -translate-x-1/2">
                    Start Streaming
                </button>
            )}
        </div>
    )
}

Aspect Ratio Support

Our primary pixel streaming provider, GeForce Now, only supports a limited set of common aspect ratios, and is principally designed to be used fullscreen on the user's device. If you are embedding the Pixel Streaming Client within your own UI, you may experience letterboxing, whereby black bars are present on either the top/bottom, or either side of the streaming video.

To minimise this, consider the aspect ratios that GeForce Now supports (see Supported Aspect Ratios, below) and try to ensure that the streaming element matches one of the given ratios. This may mean, for example, moving navigation menus from the top of the screen, to the side, to more closely match a supported aspect ratio.

Note that the aspect ratio is fixed from the moment the stream begins, and will remain fixed for the entire duration of the experience, regardless of whether the streaming element changes size or orientation (for example, as a result of the user resizing their browser window, or rotating their device.)

Supported Aspect Ratios

GeForce Now supports the following aspect ratios, and will select one that is as near as possible to that of the streaming element in your HTML:

  • 16:9

  • 16:10

  • 4:3

  • 21:9

  • 19.5:9

browser client