Skip to content

Advanced Settings

Jump to bottom Edit New page
steveseguin edited this page Feb 29, 2024 · 225 revisions

Table of contents

Overview

OBS.Ninja is a tool that can be seen as a mediator, negotiating a direct connection between a publishing device and a viewing device (such as OBS (Open Broadcasting Studio)). There are generally two links involved; one to push (publish) and one to pull (view), although links can be made to do both at the same time.

The viewer (receiver) and the publisher (sender) each play their own role in determining the qualities of a stream, so likewise each side has its own set of parameters available to them. A publisher can have multiple viewers access their video stream, with each viewer having the ability to customize the quality of the stream they receive.

The following guide details the options, syntax, values, and general use of these available settings/parameters; organized into three sections.

Passing parameters via the URL to achieve your desired stream settings

You can customize the playback of videos by adding query string parameters to the OBS.Ninja URL links, along with many other aspects. OBS.Ninja is highly flexible in this regard, letting you achieve your desired outcome without needing to code and without additional software.

For example, a simple viewer URL link such as https://obs.ninja/?view=xxxxxxx could be amended to https://obs.ninja/?view=xxxxxxx&bitrate=500, which will cause the viewer to receive the publisher's video stream at a video bitrate of 500-kbps.

Multiple parameters can be appended together by using the ampersand (&) as a separating character. For example, to view the video stream published at stream ID xxxxxxx at a video bitrate of 500-kbps and set the stereo parameter to 1:

http://obs.ninja/?view=xxxxxxx&bitrate=500&stereo=1

Some parameters, like view will accept a comma-separated list of valid values, so you can do some rather powerful combos, such as publish a video (using push) while also viewing multiple others videos. OBS.Ninja will auto-mix the videos together into a single layout for you:

http://obs.ninja/?push=aaa&view=bbb,ccc,ddd

You might notice the stream ID values I'm using (ie: aaa, bbb, etc); these can be manually created and reused. Use &push=STREAMID to publish a video and &view=STREAMID to remotely view it. If you don't manually specify a stream ID, OBS.Ninja will sometimes generate one for you.

To make up a valid stream ID of your own though, choose something with less than 31-characters of length and ensure it's AlpHaNuMerIc-only. A stream ID must also not already be in active use, else you will be provided with an error.

Community created tools and aids

List of parameters

The following options are for VERSION 17 of OBS.Ninja.

Please report any info that is out of date or incorrect; I do try to keep it up-to-date and accurate, but things slip now and then.

General options

These options apply for both viewers or publishers of a stream.

activespeaker

Auto-hides remote guests videos when added, if those guests are not speaking actively.

  • Aliases:
    • sas

chatbutton

Shows or hides the chat button.

  • Aliases:

    • cb

  • Options:

    • 0 - Hides the chat button
    • 1 - Shows the chat button

chroma={F0F|FF00FF}

Sets the background for the website to a particular hex color.

This is useful for the Electron Capture app, as you can then Chroma-key out the picked color.
Do not include the # chracter with the hex value.
Can be 3 or 6 characters in length, 0 to F, in RGB or RRGGBB format.

cleanish

Same as &clean, except it still shows the play button that allows handling gesture requirements in chrome.

cleanoutput

Keeps the output as clean as possible from UI elements.

  • Aliases:
    • clean

Hides many of the UI elements and pop-ups that may cause unwanted visual elements not desired in a high-stakes live stream.

css={url_encoded_string}

Loads a custom CSS file.

Link to a remotely hosted CSS style sheet via the URL.
You can stylize OBS.Ninja without needing to host anything more than a CSS file.
The page elements are not visible until the remote style sheet has been loaded.

URL has to be properly encoded, such as:

https://obs.ninja/?css=https%3A%2F%2Fs10.fun%2Fmain.css

You can use this tool to encode the URL you want to link to https://meyerweb.com/eric/tools/dencoder/

effects={1|2|3|4}

Applies effects to the video/audio feeds.

Options:

  • 1 - Face tracker
  • 2 - Mirror image
  • 3 - Blur background
  • 4 - Virtual greenscreen
  • 5 - Background replacement

If no value is given, it shows a "Digital video effects" panel when setting up the devices.

Green screen doesn't require SIMD support to work, although it won't work as well without it on. I leave a little warning info icon (!) if SIMD is not enabled. Please do enable Webassembly-SIMD support under chrome://flags/ if you'd like to see a large reduction in CPU load when using this feature.

flip

Inverts the video so it is upside down.

hideheader

Hides just the top header-bar.

  • Aliases:
    • noheader

This could be useful for hiding OBSN branding, making videos a bit larger at times, or for IFRAME use-case applications.

icefilter={tcp|udp|host}

Filters out ICE candidates that do not include the specified word in the candidate string.

Added for advanced use-cases and testing purposes

label[=somename]

Sets a label.

Uses the label in OBS Studio if dragging the link into OBS Studio.
Will change the name of the Browser tab to the Label specified.
Show up in the Connection debug Stats window.
If left blank, it will prompt the user for a Display Name on load.

ln={language code}

Sets the language specific interface

Defaults to: en

Some additional languages available are:

  • Russian = ru
  • French = fr
  • Japanese - ja
  • Portuguese - pt
  • Spanish - es
  • Italian - it
  • Turkish- tr
  • Ukranian - uk
  • Less Verbose - blank

You can contribute new or update existing translations.

maxconnections={value}

Limits total of view and push connections to value

meterstyle=1

Optional audio meter style type.

  • Aliases:
    • meter=1

Vertical with green to red color change based on loudness

midi={1|2|3|4}

Global hotkey support via MIDI input.

⚠️ EXPERIMENTAL ⚠️
Liable to be changed/tweaked in future versions.

midi=1

MIDI message Function
Note G3 Toggle Chat
Note A3 Toggle Mute
Note B3 Toggle Video Output
Note C4 Toggle Screen Share
Note D4 Hang up
Note E4 Raise Hand Toggle
Note F4 Record Local Video Toggle
Note G4 Enable the Director’s audio [director only]
Note A4 Stop the Director’s Audio [director only]

midi=2

MIDI message Function
Note G1 Toggle Chat
Note A1 Toggle Mute
Note B1 Toggle Video Output
Note C2 Toggle Screen Share
Note D2 Hang up
Note E2 Raise Hand Toggle
Note F2 Record Local Video Toggle
Note G2 Enable the Director’s audio [director only]
Note A2 Stop the Director’s Audio [director only]

midi=3

MIDI message Function
Note C1 + Velocity 0 Toggle Chat
Note C1 + Velocity 1 Toggle Mute
Note C1 + Velocity 2 Toggle Video Output
Note C1 + Velocity 3 Toggle Screen Share
Note C1 + Velocity 4 Hang up
Note C1 + Velocity 5 Raise Hand Toggle
Note C1 + Velocity 6 Record Local Video Toggle
Note C1 + Velocity 7 Enable the Director’s audio [director only]
Note C1 + Velocity 8 Stop the Director’s Audio [director only]

midi=4

MIDI message Function
Command = 110 with values accepted from 0 to 8 for local toggle options.
Command = 110+N where N is the guest’s order in the control room.

In this case, for hotkeying remote guests as a director:

MIDI message Function
Value 0 Opens the Transfer Popup
Value 1 Add/remove from scene
Value 2 Mute guest in scene
Value 3 Mute guest everyone
Value 4 Hangup the guest
Value 5 Toggle Solo Chat with this guest

All the above hotkey mappings are purely experimental at this time and will change based on user feedback. These mappings should allow a user to use a StreamDeck with OBS.Ninja.

Video Guides on setting it up:

https://www.youtube.com/watch?v=uidN3bLLiVk
https://www.youtube.com/watch?v=mdAzAZo65Mc

mirror={0|1|2|3}

Inverts the video so it is the mirror reflection.

Options:

  • If no value is provided, preview video is mirrored only (excluding rear cameras and OBS Virtualcam/NDI)
  • 0 - No mirroring.
  • 1 - Inverts the default. Local previews are not mirrored, but guests are mirrored.
  • 2 - Mirroring is forced for all videos.
  • 3 - Same as default, except the entire website is mirrored, including text - useful for teleprompters.

Mirroring does not work if using the browser's native video full-screen button. ( Use &effects=2 instead for this use case)
Try F11 or the Electron Capture app (right-click → Fullscreen) to hide the browser menu instead.

noaudioprocessing

Disables all audio-processing pipelines

  • Aliases:
    • noap

Disables the audio processing pipelines of both inbound and outbound audio.
Can help reduce audio distortion, echo-cancellation issues, and other audio problems, especially if your CPU is overloaded.
⚠️ Warning: Disabling audio processing will disable many features, such as audio-visualizers and loudness API functions.
⚠️ Warning: The ability to remotely mute a guest as a director (along with &gain=0) will not work if audio processing is disabled.

nocursor

Hides the mouse cursor over videos at a CSS level; useful for Electron Capture window capturing purposes.

This does not hide the mouse cursor for Chrome-based screen capture, as Chrome does not yet support that.
This feature is designed for hiding the mouse when using the Electron Capture app, to avoid mousing over the capture area by accident.
Works better in Windows than on macOS, due to OS-level limitations.

notify

Audio alerts for raised-hands and chat messages, and if somebody joins the room (director)

  • Aliases:
    • beep

obsoff

Disable the tally light effects; can be applied to both viewer or publisher.

  • Aliases:
    • oo

Ttally lights are represented as a glowing red border around videos. When the light is on, the video is considered "VISIBLE" within OBS Studio. This is based on whether OBS Studio tells OBS.Ninja if a video is active or not.
Videos on first-load in OBS, even if visible in OBS, don't glow red; it requires an initial visibility change to trigger it.

password[=some-password]

Sets a password to view a stream or to join a room.

  • Aliases:
    • pass
    • pw

⚠️ WARNING: No error is provided if the password fails or is incorrect; it will just not work.

If no password value is provided via the URL parameter, the system will prompt for one when connecting.
You will want to add the password value to the URL if loading it into OBS.
Passwords apply to both Stream IDs and Room IDs.
Please use alphanumeric-characters only; spaces or other characters may cause the mechanism to fail.
Passwords are CASE-SENSITIVE; mobile users should watch-out for auto-capitalization when entering them.
Adding &hash=HASH_VALUE will act as if &password as added.

pip

Forces the system-based PIP to trigger on the first video that loads

portrait

Optimize for vertical video.

  • Aliases:
    • 916
    • vertical

Optimize the auto-mixer to work with video streams that are in portrait mode (versus landscape).

queue

Add this to both the director URL and the guest URL.

Example director link:

https://obs.ninja?director=xxxx&queue

Corresponding room link:

https://obs.ninja/?room=xxxx&queue

There will be a new button added to the director's view, which when pressed, loads a guest into the director's room. The guest will be able to see the director and only the director then.
The director can add more guests this way, kicking out those they don't want, and continue to cycle thru the queue of guests as they join the room.
The director can then Transfer the guest(s) to another room, and when transferred, the guests are no longer considered in 'a queue' and will be able to see everyone in that new room, and vice versa.

relay

Forces TURN relay server into use.

  • Aliases:
    • private,
    • privacy

⚠️ WARNING: This costs real money to keep going. Please do not abuse the TURN server.

Forcing relay mode is provided for testing and emergency purposes. It will increase latency; sometimes by a lot.

Alternatives to relay mode include:

  • Using wired Ethernet instead of Wi-Fi will also reduce packet loss.
  • A VPN service, like Speedify, will likely be better than using a TURN server.

Uses of relay mode include:

  • Can potentially reduce packet loss with some guests on bad connections
  • Has the advantage of hiding your IP address from peers.

You can deploy your own TURN server if intending to use this feature a lot.

Please feel free to donate to OBS.Ninja to help support the provided TURN servers.
Current TURN servers are deployed in North America and Germany.
TCP/UDP on port 443.

remote={someSharedPasscode}

Allows remote operation of the zoom and focus features on Android devices.

  • Aliases:
    • rem

Android devices only. Must be enabled by both the sender and viewer with identical passcodes in order to work. This is a security precaution.
Use the mouse wheel over the video you wish to zoom in or out of.
Remote focus MAY also work as well by holding CTRL (or Command) while using the mouse wheel.
https://obs.ninja/supports will show whether your browser and default camera supports focus/zoom.
If you are the one publishing with an Android device, you can hold the screen down and move your finger up or down to zoom in and out.
The main director of a room can remotely change focus/zoom of a participant without needing the &remote command.

room={value}

Sets a room id for the session to join.

  • Aliases:

    • roomid
    • r

  • Rooms broadcast to all participants who has joined and chat messages

  • Rooms are complemented by the &director={value} function. Directors can have oversight of a room

  • Rooms limit the viewing bitrate that guests of a room can request. OBS does not have these viewing limits though.

  • Rooms have no forced limit on the number of guests allowed, but practically 10 is about the limit I'd recommend.

  • &showonly=xxx and &roombitrate=0 can be used to help increase the capacity of rooms to 30 or more.

  • An alternative to a &room is a faux-room, which can be done with: ?push=aaa&view=bbb,ccc,ddd

showlabels[=skype|ninjablue|toprounded|fire|teams|zoom]

Display labels as a video overlay.

  • Aliases:

    • showlabel
    • sl

  • Options:

    • skype
    • ninjablue
    • toprounded
    • fire
    • teams
    • zoom

Font-size of labels will adjust slightly based on the window size.
Underscores "_" used in label values will be replaced by spaces, allowing for word separation.
CSS of the styles can be set via the OBS browser source stylesheet window. The CSS class name you can customize is called "video-label".
There are some "preset" styles you can use by passing skype, ninjablue, toprounded, fire, teams, OR zoom as a value.
If no preset is passed, a default generic style is used.

stats

Shows the connection/media stats window by default.

On mobile, you can just rapidly touch the display to trigger the stats window instead.
On desktop, you can hold CTRL (or CMD) and Left-Click a video to get it's stats.
The stats URL parameter is for those like VMix users who might not be able to interact with the browser source.

stereo={0|1|2|3|4}

Sets the audio mode to stereo and changes default audio settings to improve audio quality.

  • Aliases:

    • s
    • proaudio

  • Options:

    • 0 will try to down-mix your mic to mono. Does not enable any pro-audio settings.
    • 1 enables it for both push and view (if used on both links).
    • 2 enables it just for viewing requests and not publishing requests.
    • 3 enables it for just publishing requests and not viewing requests.
    • 4 enables 5.1-multichannel audio support (Experimental and may require a Chrome flag to be set).

Defaults to either 3 or 1, depending on if a room guest or not.

  • With some browsers the viewer AND the listener of a stream both need to enable Stereo for two-channel audio to function. Not all though; some just need the viewer to enable it.

  • This is generally for advanced users who understand the consequences of enabling this.

  • Enabling this could reduce your audio mic level to be quite low, and it can also introduce audio-feedback if in a group call without headphones.

  • You can customize things further using &aec, &ag, &dn, &ab and &mono.

  • If stereo=1 is enabled:

    • It disables all audio enhancements and effects when publishing.
    • Turns off audio normalization or auto-gain (default it is on) when publishing
    • Turns off noise-cancellation (default it is on) when publishing
    • Turns off echo-cancellation (default it is on) when publishing
    • Enables higher audio bitrate playback (up to 256-kbps) when listening (viewing)

  • If the parameter is used, but left without a value, it is treated as a special case (either 1 or 3). Please see follow link for more info: https://docs.google.com/spreadsheets/d/1onfIh1hNR1Gh_mthkhmezzWNUMYKMGKPrwx7T428_hc/edit?usp=sharing

sticky

Allows a user to save and then later restore their streaming session settings via the use of web Cookies.

style={0|1|2}

  • Aliases:
    • st

Styles lets you select how media elements are displayed in OBS and for guests; audio-only elements in particular.

  • Options:
    • 1 - hides audio-only video elements from appearing. By default, they do not show in OBS already.
    • 2 - replaces audio-only elements with a visual waveform of the audio.

Styles are experimental and will undergo change, tweaks, and likely there are more to come.

tcp

Forces TCP mode if connected to a TURN server.

Versus the default, which may be UDP or TCP.

transparent

Makes the background for the website transparent using CSS.

This is useful for embedding OBS.Ninja as an IFRAME.
Not helpful with the Electron Capture app.
Not needed for OBS if using default OBS CSS stylesheet:

body {
    background-color: rgba(0, 0, 0, 0);
    margin: 0px auto;
    overflow: hidden;
}

showlist={0|1}

Toggles list of hidden guests

Options:

  • 0 - Force disable the list of hidden guests
  • 1 - Force enable the list of hidden guests

Should list user's labels in a list, along with whether they are video-muted or not, etc.
Includes microphone mute states and voice activity meters in the list.
Isn't visible by default in scenes, faux rooms, or when using &broadcast mode.
&showlist=1 will force show it and &showlist=0 will force hide it.

webp

Custom video codec for broadcasts

Must be used with broadcast, but the director doesn't need to be the designated broadcaster.

The Electron Capture app should work to allow for webp-based broadcasting even if the tab is not visible, as tab throttling is disabled with that application.
This is essentially a stream of webp-based images sent over the webRTC data-channels.
The quality by default is limited in both frame rate and resolution, as this custom video codec is very inefficient at higher resolutions and frame-rates.

Based on my testing, the webp mode is only efficient if you are keeping the bitrates under like 2mbps, so the higher qualities make little sense IMO outside of some niche use cases as they use up a lot of bandwidth.

webpquality={1..5}

Quality setting for the webp codec.

  • Aliases:

    • webpq
    • wq

  • Options:

    • 5 - 270p @ 15fps (default)
    • 4 - 270p @ 35fps (default)
    • 3 - 270p @ 50fps (default)
    • 2 - 360p
    • 1 - 720p
    • 0 - 1080p

You add this parameter to the director (or designated broadcaster) and it then sets the the quality target for the webp mode.

Source-side options

These options are what you'd add to the URL if pushing a stream, such as to the end of an iPhone invite URL.

aec={0|1}

Automatic echo-cancellation is ON or OFF.

  • Aliases:
    • ec
  • Options:
    • 0 - AEC Off
    • 1 - AEC On

May need to be disabled to use stereo on some older browsers

audiodevice={0|1|a_string_name}

Pre-configures the selected audio device.

  • Aliases:

    • adevice
    • ad

  • Options:

    • 0 - disable audio source automatically. No option to change it during setup is provided.
    • 1 - auto-select the default audio. No option to change it will be allowed.
    • cable_output - will match against "CABLE Output (VB-Audio Virtual Cable). Use any other string to match against other device names.

It can be changed after the connection has been established.
Useful for helping a remote guest skip-past the complex setup of their camera/audio.
You can pass a string name to auto-select an audio device that has a label containing that same string.
You can pass a device ID as well; see obs.ninja/devices to see the device IDs (specific to obs.ninja's domain)

autogain={1|0}

Sets whether audio auto-normalization is ON or OFF.

  • Aliases:
  • ag

autostart

Auto starts when the camera/audio device is ready.

  • Aliases:
    • autojoin
    • aj
    • as

Useful for helping a remote guest skip-past the complex setup of their camera/audio.

blind

Video playback is black for guests.

compressor

Applies a generic audio compressor to the local microphone.

This will enable the audio processing pipeline.
A compressor can help reduce spikes in audio loudness.
The compressor is off by default.

deafen

Audio playback is muted for guests.

denoise={1|0}

Turn audio noise reduction filter ON or OFF.

  • Aliases:

    • dn

  • Options:

    • 0 - Noise reduction filter OFF
    • 1 - Noise reduction filter ON

push={value}

The stream ID that you are publishing with will be the defined value.

  • Aliases:
    • permaid

If the stream ID is already in active use, an error will be shown and the stream will not publish.
If the parameter is not provided, a randomly generated stream ID will be used instead.
This is a useful parameter if you wish to reuse an invite link or if you refresh the page often.
The value needs to be 1 to 24-characters long: aLphaNumEric-characters; case sensitive.
If left empty, the stream ID will default to a random one.

secure

Disconnects communication with the handshake server as soon as possible and provides verbose feedback.

Example usage:

https://obs.ninja/?push=xxxxxxx&secure
  • The enhanced security parameter will auto-disconnect you from the handshake-server after the first peer connection is established (Publishers only are disconnected; not viewers). In effect, this makes it impossible for the server to request future handshakes from you, and hence no more future peer connections.
  • The feature also makes the connection activity verbose, letting you know when someone starts watching your stream and when that viewer disconnects.
  • The security mode also limits the max number of viewers to just one viewer, and if they do disconnect, they cannot reconnect. No one can actually; you will have to re-setup via a page refresh to let someone try connecting again.
  • This can help prevent someone from destroying a live stream due to accidentally screen sharing the streamID to the public.

The technical benefits of this include:

  • The handshake server has no way of talking to the publisher after the stream starts. Fully decentralized once initialized.
  • The publisher cannot be spammed by "Watch Stream" requests if the invite link gets shared accidentally
  • The publisher can clearly see when someone has joined and when someone has disconnected
  • Increased security and privacy, with just some minor added inconveniences.

height={value}

Sets the maximum height of the video allowed in pixels.

  • Aliases:

    • h

  • Actual height may be less based on bandwidth allowances

  • If the camera cannot support the height, it will fail.

  • Limiting the height can force the camera to use higher frame rates

  • Limiting the height can reduce the CPU load

  • https://obs.ninja/supports will list the support resolutions of your default camera.

  • https://webrtchacks.github.io/WebRTC-Camera-Resolution/ Is a tool to help you find the resolutions supported by your camera

  • You can use &scale=50 also, as a viewer, to scale down a selected width/height to something more exact.

width={value}

Sets the maximum width of the video allowed in pixels.

  • Aliases:

    • w

  • Actual width may be less based on bandwidth allowances.

  • If the camera cannot support the width, it will fail.

  • Limiting the width can force the camera to use higher frame rates.

  • Limiting the width can reduce CPU load.

framerate={frame rate}

Sets the maximum frame rate of the video in frames per second.

  • Aliases:
    • fps
    • fr

Actual frame rate could be less.
If the camera cannot support this frame rate, it will fail.
Limiting the frame rate can reduce the CPU load.
Limiting the frame rate can reduce bandwidth.

minipreview

Mini self preview at the top right corner.

  • Aliases:
    • mini

Default behavior when broadcast mode is on.

mutespeaker

Auto mutes guest's speaker.

  • Aliases:
    • ms

Sets the speaker to be muted by default for a guest

quality={0|1|2}

Less strict way to set quality.

  • Aliases:

    • q

  • Options:

    • 0 is about 1080p60, depending on hardware
    • 1 is about 720p60, depending on hardware
    • 2 is about 360p30, depending on hardware

Presets the "quality" setting for a guest.
Not "strict" and is less likely to give errors than explicit resolution requests.

videodevice={0|1|a string_name}

Pre-configures the selected video device.

  • Aliases:

    • vdevice
    • vd

  • Options:

    • 1 - auto-select the default video camera. No option to change it will be allowed.
    • 0 - disable the video camera automatically. No option to change it during setup is provided.

It can be changed after the connection has been established.
Useful for helping a remote guest skip-past the complex setup of their camera/audio.
You can pass a string name to auto-select a video device that has a label containing that same string.
You can pass a device ID as well; see obs.ninja/devices to see the device IDs (specific to obs.ninja's domain).

device={0|1|string_name}

Same as &audiodevice or &videodevice, but applies to both.

  • If you set &device=0, you disable audio and video inputs, but chat is still available. Chat-only guests can access a group-room this way.

mute

Starts with the microphone muted by default.

  • Aliases:
    • muted

videomute

Auto mutes guest's video.

  • Aliases:
    • vm

Sets image to be muted by default for guests.

pcm

Video recordings will be saved as Video + PCM audio format

preview

Forces the guest to have a self-preview, overriding &broadcast.

  • Aliases:
    • showpreview

nopreview

Disables the local self video preview.

  • Aliases:
    • np

If you don't want to see yourself when in a group chat, this will hide your video.
⚠ iOS users: This flag will break stuff; You must have a preview if using those devices and wanting to publish.

nosettings

Disables the local settings button.

You won't be able to change video or audio feeds after initially selecting them. This prevents guests accidentally changing their webcam or microphone after entering a room.

  • Hides the screen-share button as well.

ssb

Forces the screen-share button to appear for guests.

Even if they are on an incompatible device or are using &nosettings.

hands

Enables a "Raise Hand" button for guests.

  • If pressed, and the user is in a room, the room's director will get a notification that the user pressed the button
  • It will do nothing if the room does not have a director in it.
  • The director can dismiss the user's action

micdelay={milliseconds}

Delays the microphone by specified time in ms

  • Aliases:
    • md

maxframerate={fps}

Like &framerate, except it will allow for lower frame rates if the specific frame rate requested failed

  • Aliases:
    • md

order={integer}

The order priority of a source video when added to the video mixer.

  • Default is 0 and the passed value needs to be an integer value.
  • The director can change this value remotely, changing the order of a video in a mixed scene of videos.
  • If two videos have the same order value, the mixer will decide on its own which is drawn first of the two.
  • If a video has a higher order value assigned to it, it will be drawn first in the order.
  • Order is Left to Right; Top to Bottom.

outboundaudiobitrate={bitrate in kbps}

Target audio bitrate and max bitrate for outgoing audio streams

  • Aliases:
    • oab

outboundvideobitrate={bitrate in kbps}

Target video bitrate and max bitrate for outgoing video streams

  • Aliases:
    • ovb

record={bitrate}

Record functionality for guests.

Adds a Record button to the control bar of guests that allows for video/audio recording of local feeds.

Options:

  • 0 - No video recorded; audio tentatively recorded as 32bit PCM lossless.
  • negative integer - No video recorded; audio recorded as {bitrate}kbps OPUS file. Eg: -120 - Audio only at 120kbps.

Recorded file properties:

  • File format - WebM.
  • File Codec: H264 or VP8 for video; OPUS or PCM for audio.
    Usually up to the browser.

Default bitrate will record at around 6000-kbps, but it will still prompt still for value if not set.
The Director of a room will be notified if a user is recording and they can start/stop the recording.
The Director of a room can trigger the record function remotely, even if the &record parameter has not been added.
The video/audio will be saved in real-time to the guest's local download folder.
Do not close the browser or turn off the computer while it is recording; you may lose the file or have a partial capture.
The recording should stop automatically when the guest hangs-ups manually.

It will automatically capture with Stereo audio and echo cancellation off, if available. You can use https://obs.ninja/convert to convert from WebM file formats to opus or wav file formats, without transcoding and without downloads.

Bitrate Thresholds:

4000, Inbound audio: 128kbps; Recorded audio: 128kbps.
2500, Inbound audio: 80kbps; Recorded audio: 128kbps.
< 2500, Inbound audio: 32kbps; Recorded audio: 32kbps.

When recording with PCM, (&pcm or w/e) the inbound audio bitrate will be at 256kbps. (regardless of video bitrate)

gain={integer}

Applies a gain multiplier (as a percentage) to the local microphone.

  • Values:
    • 0 - mutes the microphone so that only the Director can unmute it; the guest cannot unmute.
    • 100 - full volume; default.
    • Any other value

⚠️ This will enable the audio processing pipeline.

Can be remotely controlled by the Director if in a room.
Only applies to the first audio-source selected by a guest, if there is more than one selected.
If audio processing is on, then this should be available by default for the director to remotely control.

limiter

Applies a generic audio limiter to the local microphone.

⚠️ This will enable the audio processing pipeline. A limiter is like an aggressive compressor.
It cannot be used along with the &compressor option.
The limiter is off by default.

equalizer

Provides access to a generic audio equalizer that can be applied to the local microphone.

  • Aliases:
    • eq

⚠️ This will enable the audio processing pipeline.

It can be accessed via the Settings page or the Director can remotely adjust it.

lowcut={hz}

Adds a low-cut filter

Default cut off frequency is 100hz.

⚠️ This will enable the audio processing pipeline.

forceios

Forces iOS devices to publish video to this room guest.

By default, iOS devices do not publish video to other guests in a group room.
They can only publish THREE (3) video streams at any one time, before things explode.

webcam

Disables Screen-sharing as an option.

  • Aliases:
    • wc

Full-screens the Webcam selection window

screenshare

Disables Webcam-sharing as an option.

  • Aliases
    • ss

Full-screens the Screenshare selection window

screenshareid={id}

  • Aliases
    • ssid

When screen sharing as a guest in a group room, the screen share will now create a second stream for the screen share, keeping your webcam also.
This will preset the ID the screenshare will have.

fileshare

Allows the user to select a video or audio file as a source for streaming.

  • Aliases:
    • fs

The stream can be paused and scrubbed like a normal video/audio file.
It will auto-loop when it ends.
Supports audio-only files as well as common video formats. Depends on your browser.
If you mute the video, it will mute the video for all the viewers as well.
It is extremely simple in functionality and is only available when the URL is used.
The resolution used will be limited by the video's native resolution.
⚠️ The video will be transcoded for each connected guest!

roombitrate={bitrate in kbps}

Limits any guest viewer in the group chat room from pulling the video stream at more than the specified bitrate value.

  • Aliases:
    • roomvideobitrate
    • rbr

Does not impact what the director sees and does not limit the quality of what OBS has access to.
If set to 0, then it disables access to your video for other guests in a group room.
This is like maxbitrate, but roombitrate only applies to fellow group room guests.
Practically, a guest normally won't pull more than 1200-kbps and that's only if they click the HQ full-window button.
Set to 600-kbps, 200-kbps, or 80-kbps if the goal is to reduce CPU load. (2x, 3x, or 4x down-scaling is applied at those bitrate limits)

maxbitrate={bitrate in kbps}

Limits the max video bitrate out for this publisher, per stream out.

  • Aliases:
    • maxvideobitrate
    • mvb

Not set by default.
Set to 600-kbps, 200-kbps, or 80-kbps if the goal is to reduce CPU load also. (2x, 3x, or 4x down-scaling is applied at those bitrate limits).
Useful if you are a director and you wish to prevent guests from pulling more than 500-kbps (LQ) or 1200-kbps (HQ) when in broadcast mode.

maxviewers={value}

  • Aliases:
    • mv

Limits the number of viewers allowed.

  • Useful for iOS devices that might explode if more than 3 video viewers connect
  • Useful to prevent publicly shared guest links from being crashed due to too many viewer requests

ptz

Enables pan/tilt control of the device, if compatible.

This will trigger a new permission popup though.

transcribe={en-US}

Enables transcription and closed captioning.

  • Aliases:
    • trans
  • Options:
    • en-US for American English.
    • de-DE for German.
    • pt-PT for Portuguese.
    • any other xx-XX style language code. (check here)

Uses default system mic as a source and cannot be muted.

⚠️ WARNING: Does not work in Safari! ⚠️

sensor={value}

Access device sensor data at {value} rate.

Gyroscopic, accelerometer, magnetometer data can be pushed out.
Enable with &sensor=30 (30hz).
Results show up in the remote stats log or the remote IFRAME API.
Useful for VR live streaming support, where you want to capture a smartphone's movement, as well as video.

website

Only shares a website with viewers

  • Aliases:
    • iframe

Viewer's (OBS Link) options

These options are what you'd add to the URL if pulling or viewing a stream, such as on the end of the links you are adding to an OBS Browser Source.

view[=value1,value2,value3,...,valueN]

  • Aliases:
    • streamid
    • v
    • pull

Defines the stream or streams you are receiving, by their stream IDs.

Optional if you are publishing a stream using push.
If the view parameter is not added, the default behaviour will occur.
If the view parameter is provided, it will try to play any stream listed.
If the view parameter is provided, but no values are provided, no streams will play; only publishing will be allowed.

This is useful is you wish to publish a video into a group chat room, but only view video from specific known participants.
This is also useful if you wish to create ad-hoc group chat sessions without using a group room.
Videos will auto-load when they are available if not already.

exclude=[value1,value2,value3,...,valueN]

Same concept as &view, except does the opposite.

Any stream ID listed as a value will NOT be played or requested.
Excluding a stream ID will prevent even a peer connection, so video, audio, or chat can be had.

codec={vp8|vp9|h264|av1}

Sets the codec to encode the video.

H264

  • H264 may offer hardware encoding for better battery life with mobile and embedded devices
    • iOS devices should generally use H264, but the max resolution supported then is 1280x720.|
    • macOS systems generally prefer H264 and will sometimes hardware-encode

VP8

  • VP8 is the default in most cases, even though Apple devices may default to H264.
    • OBS on PC does not handle packet loss well when using VP8.
    • The Electron Capture app handles VP8 very well.
    • iOS devices can stream at 1080p30 or 720p60 when using VP8, but they get warm in doing so

VP9

  • VP9 offers better compression than VP8, but is also more CPU-intensive to use.
    • VP9 seems to reduce the chance of "rainbow puke" video problems in OBS Studio vs VP8
    • Do not feel compelled to stream at HD resolutions; even 540p can look good and runs much cooler.

AV1

  • AV1 is the most advanced codec, but also the most CPU-intensive to use.
    • Requires Chrome v90 or newer on both publisher and viewer to work
    • Experimental at this point in time; may not perform well.

bitrate={bitrate in kbps}

  • Aliases:
    • videobitrate
    • vb

Sets the "desired target" bitrate in kbps.

  • Value is an integer reflecting kilobits per second
  • Default value will target around around 2500 to 4000.
  • The maximum achievable bitrate is around 60,000-kbps (60000)
  • Lowering the bitrate can sometimes reduce CPU load, bandwidth, and stuttering issues
  • You might want to increase the bitrate for game streams, to ensure smooth frame rates.
  • Not compatible with Firefox browsers.

audiobitrate={bitrate in kbps}

  • Aliases:
    • ab

Manually sets the audio bitrate in kbps

  • The default is around 32-kbps per track with a mono-channel (VBR on by default)
  • The audio codec used is OPUS and the target sample rate is 48khz
  • 510-kbps is the highest value allowed, with around 300-kbps the highest value for a mono-channel track.
  • When an audio bitrate is manually specified, CBR is enabled by default.
  • If you do not disable Echo-Cancellation (aec) and denoise, audio quality will still be stuck at telephone quality.
  • Setting the audio bitrate to be very high can sometimes cause video bitrates on weak connections to become stuck at around 30-kbps.
  • For reference, Spotify uses around 96-kbps for stereo audio on mobile devices

controlroombitrate={bitrate in kbps}

Allows a guest to control their total room video bitrate dynamically from the settings panel (under video settings).

  • Aliases:

    • crb

  • When parameter added, a slider appears in the guest’s settings menu.

  • This feature could be useful for guests that have limited CPU or Network bandwidth to self-regulate.

  • Lowering this slider will reduce the video bitrate of incoming video streams.

  • It will not allow the guest to increase the room bitrate's limits; only lower them

  • I suppose while listed as a 'viewer' setting, you need to be a publisher also to access this value (as the settings button is needed).

  • Consider using &totalroombitrate if you wish to increase the bitrate higher than the default max of ~ 500-kbps.

maxptime={60}

Maximum packet size of audio in milliseconds. 60ms is common. 30ms is reasonable.

  • If you do not know what this is, you definitely don't want to touch it.
  • Optimized already, but it's available for experimentation and fun if desired.

minptime={10}

Minimum packet size of audio in ms. 10ms is lowest that you can set in Chromium I think.

  • If you do not know what this is, you definitely don't want to touch it.
  • Optimized already, but it's available for experimentation and fun if desired.

ptime={Integer}

Audio packet size of audio in ms.

  • If you do not know what this is, you definitely don't want to touch it.

samplerate={Integer}

  • Aliases:
    • sr

Audio playback sample-rate, in Hz. (not capture or transmission sample-rate)

  • This is mainly for debugging audio distortion or clicking issues
  • Sometimes it can remove clicking when used, even if set to the typical 48000 value

enhance

Tells the remote source that you would like them to prioritize the audio stream over other streams.

  • May not be compatible with all remote sources; depends on the browser they have
  • Prioritizing audio may cause problems elsewhere, such as for other viewers or for video streams
  • Prioritization applies to both encoding and networking sending of audio packets
  • May override custom ptime values.
  • This option may be useful in reducing audio 'clicking', but likely will be just as effective as a placebo.

For advanced users, this sets the following of the audio's stream: networkPriority = "high"; priority = "high"; adaptivePtime = true;

For more details, please see: https://www.w3.org/TR/webrtc-priority/#dom-rtcrtpencodingparameters-networkpriority

maxpublishers={int}

  • Aliases:
    • mp

Limits the number of remote peer connections that are publishers.

totalroombitrate={bitrate in kbps}

  • Aliases:
    • totalroomvideobitrate,
    • trb
  • Defaults to: 500

The total bitrate a guest in a room can view video streams with; their combined bitrate total of all inbound video streams.

  • Split between the number of streams that guest is viewing
  • Does not override any limits other guests in the room may set for their outbound bandwidth
  • With 6-guests in a room, the default has each guest requesting 100-kbps from each other per stream.

mono

Has the inbound audio playback as mono audio

  • If using &proaudio, this will retain the publishing benefits of &proaudio, while keeping the audio as mono instead of stereo
  • Will not work with Firefox; Firefox's playback will still be in stereo if the source is stereo.
  • Audio bitrates may be reduced from 256-kbps to 128-kbps, if not explicitly stated, in some cases.

vbr

Sets the audio bitrate to be variable, instead of constant, but only when an audio bitrate is manually specified.

  • By default, Chrome uses a variable bitrate with a cap at around 32-kbps with mono-audio.
  • When manually specifying a bitrate, Chrome keeps the audio bitrate pretty constant, even if VBR is turned on.

noaudio={xxx,yyy}

  • Aliases:
    • na

Delivers video only streams; audio playback is disabled.

novideo={xxx,yyy}

  • Aliases:
    • nv
    • showonly

Disables all video playback on the local computer, except for any stream ID that is listed.

  • Useful for reducing the CPU and network load on other connect peers if voice-chat is sufficient.
  • Join a group-room as audio-only, to limit load on the guests
  • Useful for a large group room where you want everyone in the room to see only the OBS Virtualcam output.
  • Consider using &broadcast option instead of this flag as it is better suited for presenting a single feed to a group than using &novideo alone.

When used together with noaudio (&novideo&noaudio), prevents guest room member from seeing or hearing other member's audio or video feeds.

  • Useful for directors who may wish to only issue commands or text chat, but not need to see video or audio.

broadcast={xxx}

Like &novideo, but with some extras added to make setup of large group rooms easier.

  • Disables the local video preview
  • Disables the video from other guests, unless their stream ID is specified as the {xxx} value.
  • If left empty, it allows the DIRECTOR's video to appear, even if the director's stream ID is not known.
  • Hides the audio-only guest windows that would appear normally; this is akin to &style=1
  • Disables the top page header (&noheader)

buffer={milliseconds}

Sets the video buffer.

⚠️ WARNING: This will only work if playing the video in Chrome/Chromium v76 or newer (OBS uses v75).

  • &buffer=0 will force the audio to be in sync with the video, with the video playing back with minimal delay.

  • OBS will support the buffer command in the future, but it currently does not

  • Adding a buffer > ~ 100 will add a time delay to the video

  • Adding a buffer > ~ 100 can help reduce video problems, such as frame jitter

  • Works well with the Electron Capture app

  • Using may stopEcho Cancellation from working

sync={milliseconds}

Sets an offset (in ms) for the automatic audio sync fix node.

&buffer=0 or &sync=0 will do the same thing -- it will try to auto-sync video and audio.
Tiny negative offsets may work, like &sync=-25 is possible, but large negative offsets will not work.
No clue if it is supported in OBS or not; works in Chromium/Chrome v76 or newer tho. Useful if the video device has a large delay that needs compensating for that isn't fixed automatically.
&sync=500 without the &buffer command also will only add an audio delay; there will be no additional video buffer or delay.
Using may stop Echo Cancellation from working.

scale={0..100}

Scales the video resolution of the inbound video by the given percent.

Intended for use by the viewer of inbound video.
Example: If the video inbound has a resolution of 1920x1080, a &scale=50 would limit it to 960x540 instead.
The nice thing about this is that it doesn't matter which resolution their camera supports; the scale is software based and doesn't care about resolutions or aspect ratios.
This can help a viewer reduce frame stuttering, cpu load, and improve frame rates, without having to have the guest rejoin the stream.
Requires the publisher of the stream to support dynamic scaling; Firefox and Chrome should be supported.

optimize= {bitrate}

Video bitrate reduced when the video is not visible in OBS (not active in a scene).

Values are in kbps.
Default bitrate is 600-kbps unless specified.
This is mainly there to help with reducing load for OBS and for guests.
This does not work with iPhone-sourced video streams.
Can take a few seconds for the bitrate to ramp back up after it becomes active again.
You can change the default from 600-kbps to something else by passing your own value to it.
optimize=0 will disable the video track when not considered visible in OBS.

streamlabs

Tells OBS.Ninja to not block OBS.Ninja from attempting to run when using Streamlabs OBS for macOS.

  • For normal OBS users, update to OBS 26.1.2 on macOS to obtain native support for OBS.Ninja in OBS.
  • StreamLabs for OBS doesn't yet have full support for OBS.Ninja; consider the Electron Capture app if it fails to work well.

obsfix={some-positive-integer|off}

Disables or adjusts the sensitivity of the VP8/VP9 Codec packet loss 'fix' for OBS.

  • It's on by default and set to 15 if only using OBS and if using the VP8/VP9 video codec
  • There is a bug in OBS where the VP8 codec (default in most cases) does not handle packet loss events. This function attempts fixes its.
  • You can disable this 'fix' by passing it the value 0 or off.
  • When on, it will trigger a keyframe request to combat pixel smearing caused by packet loss and poor network conditions
  • Triggers around every 3-seconds if needed; may not activate often with very light packet loss.
  • May lower video quality, or may not be desirable, so this flag lets you disable it.
  • Stream pushers can open the debug/stats menu and manually send keyframes also.
  • VP9 is far less prone to packet loss issues, but it can still happen with heavy packet loss.
  • Increasing the integer value passed to &obsfix will reduce the frequency and sensitivity of the keyframe request.

keyframerate={milliseconds}

This tells the remote publishers to send keyframes at a specified rate

  • Could be useful if packet loss is causing a lot frame corruption
  • If you make it less than 1000ms, you will face a pretty steep drop in video quality.
  • It may not work at all if set too low; under 500ms didn't work at all in my testing.

director={room_name}

  • Aliases:
    • dir

Enters a room as the director, instead of a guest.

  • First director to join a room claims the room
  • Other faux-directors can join, but they won't have any power over guests
  • If the first director refreshes, they will likely still claim the room even if other faux-directors are already connected.
  • Directors have powers over some aspects of those in a group room and its scenes, such as the ability to hangup remote guests

turn={ false | off | username;password;turnserveraddress}

Passes details on related to the TURN server (if in use).

  • &turn=false or &turn=off disables the use of the TURN servers
  • There is a TURN server provided by default, provided by Steve for free, for now.
  • The default OBS.Ninja TURN server address is turn:turn.obs.ninja:443 (well, there are multiple now actually)
  • The provided free TURN servers are located (as of November 2020) in Canada and Germany. Please do not abuse.
  • Using your own TURN server can improve video quality for some users; ideally one hosted locally to your location. Details are provided in the code repo no how to deploy your own (turnserver.md)
  • About 1 in 10 users need a TURN server to use OBS Ninja; if you are having problems, check to see if they are using the TURN server.
  • Using a TURN server can hide your IP address
  • https://obs.ninja/speedtest performs a connection test using the TURN server.
  • You can see if you are using the TURN server by checking the connection stats window (Left-Click + CTRL while viewing a video)
  • In the stats, "Relay" implies connected to a TURN server. HOST implies connected via a LAN. SRFLX/PRFLX implies connected directly via STUN.

scene={value}

Sets a scene, used by a room's director.

  • Must be used in conjunction with a room parameter.
  • scene=0 by default has all videos in the room automatically added to the scene. They cannot be removed.
  • scene=1 by default has no videos added to the scene. Videos need to be added manually by the director. Videos not yet added to the scene are connected, and streaming at around 400-kbps, so when they become active they appear immediately. Bitrate will ramp up after a second to the target bitrate of, normally, 2500-kbps or whatever is set via the URL.
  • scene=2 is like scene=1, except the video streams that are not yet added to the scene yet are disable with 0-bitrate used. They are connected, but not actively streaming any video data, so it takes a moment longer for videos to appear once added
  • scene=N, where N is a positive integer -- just like scene=2. There are buttons marked S3, S4, .. S8 in the director's room to control these scene types.
  • When using a scene, if you manually specify a video via the &view parameter, it automatically is added to the scene.
  • Audio of videos in scenes can be controlled by the director: volume and mute are options.
  • In v17.2 of OBS.Ninja, if using &view in a scene link, the director won't be able to remotely control the scene. This applies to Solo links.

hidemenu

Hides the OBS.Ninja-branded menu and header bar.

Useful for making videos larger for guests by freeing up space

sink={sink device ID}

Outputs the audio to the specified audio output device, rather than the default.

Designed to be used in conjunction with https://obs.ninja/electron.

⚠️ WARNING: Device IDs are tied to the browser + domain + cookie session combination.

outputdevice={label}

Pre-selects the audio output device.

  • Aliases:
    • od
    • audiooutput

Like &sink, but selects the audio output device based on a partial string that matches the device's label/name.

  • Matches on "string contains"; lower case, with underscores marking special characters or spaces.
  • &sink takes priority, if used, and &sink is more strict in matching.
  • &outputdevice=labelname is consistent across domains / cookie sessions, while &sink=deviceid isn't.
  • if parameter's value is left blank, it hides the option to change the output device, including under the settings cog.

channels={value}

Specifies the number of output audio channels you wish to mix up or down to.

Designed to be used with &channeloffset.

Please see here for detailed testing results with different audio devices: https://docs.google.com/spreadsheets/d/1R-y7xZ2BCn-GzTlwqq63H8lorXecO02DU9Hu4twuhuA/

channeloffset={value}

Shifts audio channels 0 and 1 up channels, based on the offset value.

  • Total channels is assumed to be 8 if this is used and not otherwise specified
  • Does not work with all audio output devices and may require experimentation

Please see here for detailed testing results with different audio devices: https://docs.google.com/spreadsheets/d/1R-y7xZ2BCn-GzTlwqq63H8lorXecO02DU9Hu4twuhuA/

cc

Enables displaying of closed captioning text.

Pushed from the source with &transcribe.

fontsize={value}

Let you set font-size of the closed captions show them with &cc

novideobutton

Disables the video button. Guests can't mute video.

  • Aliases:
    • nvb

nomicbutton

Disables the mic button. Guests can't mute audio.

  • Aliases:
    • nmb

Director-specific options

channels

Shows buttons to let the director select which audio channel output a video will output to.

  • Left and right is available for most users; channels 1 and 2
  • Up to 6-channels is possible, if your output device supports it.
  • On Windows, you might need to select 5.1 surround sound with your device in the Windows audio settings
  • On macOS, you might want to consider using SoundFlower, as it seems the most correct with its routing.

(Update in v17: &channels is displayed by default now)

cleandirector

Hides the invite URL options in the Director's room.

Allows for a cleaner looking interface. Useful if using IFRAMES I maybe.

scenes

Will show a new set of buttons to let a director control what scene a guest video appears in.

  • Scene=2 is still quite special, as it will only show the last video added, so keep that in mind currently
  • You can create custom view links for these new scene options; these links are not provided for you.
  • An example link might be, https://obs.ninja/?room=xxxx&scene=4 , which correlates to button "S4".

(Update in v17: &scenes is displayed by default now)

rooms=[room1,room2,...]

Quick director access to a list of rooms for transfering guests.

Adds buttons to the directors control centre control bar for each room listed under this parameter. Pressing any of these buttons will arm the transfer buttons beneath each caller with the chosen room name, allowing callers to be quickly moved from one room to another.

Arming can be disabled by clicking the room name again.
If the current room is in the list it will be ignored.
If &cleanoutput is enabled, rooms parameter is ignored.

showdirector

Let's director perform alongside guests.

As a director, you will now appear as a performer kind of like other performers.
Add/remove from scene, highlight, record, order, and the solo-link is easy to access.

Add a custom footer
Add a custom sidebar
Clone this wiki locally