├── requirements.txt ├── .gitignore ├── docs ├── Platforms │ ├── Linux.md │ ├── Windows UWP & Hololens.md │ ├── Oculus OVR.md │ ├── Magic Leap.md │ ├── Windows Desktop.md │ ├── iOS.md │ ├── Android.md │ └── MacOS.md ├── dissonance.png ├── images │ ├── AecStatus.png │ ├── AecSettings.png │ ├── Bolt-State.png │ ├── BoxCollider.png │ ├── VAD_States.png │ ├── VadDebugUI.png │ ├── VoiceSettings.webp │ ├── OVR Local Avatar.png │ ├── VoiceSettings2.webp │ ├── AudioMixing_Ducking.png │ ├── HLAPI_QoS_Channels.png │ ├── TeamChat_Inspector.png │ ├── AudioMixing_Distortion.png │ ├── DissonanceComms_Tokens.png │ ├── VoiceSettings_Editor.png │ ├── AudioMixer_WithAecFilter.png │ ├── AudioPluginDissonance.so.png │ ├── GlobalChatRoom_Inspector.png │ ├── RoomConfiguration_Lobby.png │ ├── BroadcastToSelf_Inspector.png │ ├── DissonanceComms_Inspector.png │ ├── RoomTriggerVolume_Inspector.png │ ├── VoiceBroadcastTrigger_PTT.png │ ├── VoiceReceiptTrigger_Default.png │ ├── VoiceReceiptTrigger_Rooms.png │ ├── VoiceReceiptTrigger_Tokens.png │ ├── AudioSource_OutputHighlighted.png │ ├── PlayerPrefab_PositionalAudio.png │ ├── PlayerProximityChat_Inspector.png │ ├── VoiceBroadcastTrigger_Default.png │ ├── VoiceBroadcastTrigger_Player.png │ ├── VoiceBroadcastTrigger_Targets.png │ ├── VoiceReceiptTrigger_LobbyRoom.png │ ├── VoiceReceiptTrigger_Overview.png │ ├── PlaybackPrefab_OutputHighlighted.png │ ├── VoiceBroadcastTrigger_LobbyRoom.png │ ├── VoiceBroadcastTrigger_Overview.png │ ├── VoiceBroadcastTrigger_Positional.png │ ├── VoiceBroadcastTrigger_Priority.png │ ├── AudioSource_SpatializeHighlighted.png │ ├── ProximityReceiptTrigger_Inspector.png │ ├── VoiceBroadcastTrigger_DifferentPTT.png │ ├── ProximityBroadcastTrigger_Inspector.png │ ├── VoiceBroadcastTrigger-AmplitudeFaders.png │ ├── VoiceBroadcastTrigger_SectionsOverview.png │ ├── VoiceBroadcastTrigger_Section_AccessTokens.png │ ├── VoiceBroadcastTrigger_Section_ChannelType.png │ ├── VoiceBroadcastTrigger_Section_ActivationMode.png │ ├── VoiceBroadcastTrigger_Section_AmplitudeFaders.png │ └── VoiceBroadcastTrigger_Section_ChannelMetadata.png ├── css │ ├── pygment_tweaks.css │ └── header_tweaks.css ├── Tutorials │ ├── Spatializer-Plugin.md │ ├── Global-Chat-Room.md │ ├── Push-to-Talk.md │ ├── UsingIMicrophoneSubscriber.md │ ├── Direct-Player-Transmit.md │ ├── Player-State.md │ ├── Text-Chat.md │ ├── Channel-Priority.md │ ├── Team-Chat-Rooms.md │ ├── Access-Control-Tokens.md │ ├── Channel-Volume.md │ ├── Script-Controlled-Speech.md │ ├── Position-Tracking.md │ ├── Playback-Prefab.md │ ├── Proximity-Chat.md │ ├── Position-Tracking-For-Bolt.md │ ├── Directly-Using-Channels.md │ ├── Server-Admin-API.md │ ├── Collider-Chat-Room.md │ ├── Custom-Position-Tracking.md │ ├── Audio-Mixing.md │ ├── Custom-Microphone-Capture.md │ └── Acoustic-Echo-Cancellation.md ├── Basics │ ├── Licensing.md │ ├── Other-Integrations.md │ ├── Getting-Started.md │ ├── Quick-Start-Forge-Remastered.md │ ├── Quick-Start-Unity-NFGO.md │ ├── Introduction-To-Chat-Rooms.md │ ├── Quick-Start-Photon.md │ ├── Quick-Start-PureP2P.md │ ├── Quick-Start-Fusion.md │ ├── Quick-Start-Mirror.md │ ├── Quick-Start-Photon-Bolt.md │ ├── Quick-Start-DR2.md │ ├── Quick-Start-UNet-HLAPI.md │ ├── Quick-Start-Steamworks.Net-P2P.md │ ├── Quick-Start-TNet3.md │ └── Choosing-A-Network.md ├── javascript │ └── redirector.js ├── Reference │ ├── Other │ │ ├── TextChat.md │ │ ├── Rooms.md │ │ ├── PlayerChannels.md │ │ ├── RoomChannels.md │ │ ├── RemoteChannel.md │ │ ├── RoomChannel.md │ │ ├── PlayerChannel.md │ │ ├── VoicePlayerState.md │ │ └── VoiceSettings.md │ ├── Components │ │ ├── Voice-Receipt-Trigger.md │ │ ├── Voice-Proximity-Receipt-Trigger.md │ │ ├── Voice-Proximity-Broadcast-Trigger.md │ │ ├── Voice-Broadcast-Trigger.md │ │ └── Dissonance-Comms.md │ ├── Audio │ │ ├── BaseMicrophoneSubscriber.md │ │ ├── IMicrophoneSubscriber.md │ │ ├── IMicrophoneCapture.md │ │ └── VoiceSettings.md │ └── Networking │ │ ├── IServerClientState.md │ │ └── Network-Protocol.md └── index.md ├── .vscode └── spellright.dict ├── .github ├── workflows │ └── ci.yml └── ISSUE_TEMPLATE.md ├── Readme.md └── mkdocs.yml /requirements.txt: -------------------------------------------------------------------------------- 1 | mkdocs-material==6.2.4 -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | site 2 | Dissonance Documentation -------------------------------------------------------------------------------- /docs/Platforms/Linux.md: -------------------------------------------------------------------------------- 1 | # Linux 2 | 3 | Running Dissonance on a Linux PC has no runtime dependencies. -------------------------------------------------------------------------------- /docs/dissonance.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/dissonance.png -------------------------------------------------------------------------------- /.vscode/spellright.dict: -------------------------------------------------------------------------------- 1 | Netcode 2 | Steamworks 3 | comms 4 | preprocessed 5 | boolean 6 | Readonly 7 | LuminOS 8 | -------------------------------------------------------------------------------- /docs/images/AecStatus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/AecStatus.png -------------------------------------------------------------------------------- /docs/images/AecSettings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/AecSettings.png -------------------------------------------------------------------------------- /docs/images/Bolt-State.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/Bolt-State.png -------------------------------------------------------------------------------- /docs/images/BoxCollider.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/BoxCollider.png -------------------------------------------------------------------------------- /docs/images/VAD_States.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VAD_States.png -------------------------------------------------------------------------------- /docs/images/VadDebugUI.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VadDebugUI.png -------------------------------------------------------------------------------- /docs/images/VoiceSettings.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceSettings.webp -------------------------------------------------------------------------------- /docs/images/OVR Local Avatar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/OVR Local Avatar.png -------------------------------------------------------------------------------- /docs/images/VoiceSettings2.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceSettings2.webp -------------------------------------------------------------------------------- /docs/images/AudioMixing_Ducking.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/AudioMixing_Ducking.png -------------------------------------------------------------------------------- /docs/images/HLAPI_QoS_Channels.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/HLAPI_QoS_Channels.png -------------------------------------------------------------------------------- /docs/images/TeamChat_Inspector.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/TeamChat_Inspector.png -------------------------------------------------------------------------------- /docs/images/AudioMixing_Distortion.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/AudioMixing_Distortion.png -------------------------------------------------------------------------------- /docs/images/DissonanceComms_Tokens.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/DissonanceComms_Tokens.png -------------------------------------------------------------------------------- /docs/images/VoiceSettings_Editor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceSettings_Editor.png -------------------------------------------------------------------------------- /docs/images/AudioMixer_WithAecFilter.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/AudioMixer_WithAecFilter.png -------------------------------------------------------------------------------- /docs/images/AudioPluginDissonance.so.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/AudioPluginDissonance.so.png -------------------------------------------------------------------------------- /docs/images/GlobalChatRoom_Inspector.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/GlobalChatRoom_Inspector.png -------------------------------------------------------------------------------- /docs/images/RoomConfiguration_Lobby.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/RoomConfiguration_Lobby.png -------------------------------------------------------------------------------- /docs/images/BroadcastToSelf_Inspector.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/BroadcastToSelf_Inspector.png -------------------------------------------------------------------------------- /docs/images/DissonanceComms_Inspector.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/DissonanceComms_Inspector.png -------------------------------------------------------------------------------- /docs/images/RoomTriggerVolume_Inspector.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/RoomTriggerVolume_Inspector.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_PTT.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_PTT.png -------------------------------------------------------------------------------- /docs/images/VoiceReceiptTrigger_Default.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceReceiptTrigger_Default.png -------------------------------------------------------------------------------- /docs/images/VoiceReceiptTrigger_Rooms.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceReceiptTrigger_Rooms.png -------------------------------------------------------------------------------- /docs/images/VoiceReceiptTrigger_Tokens.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceReceiptTrigger_Tokens.png -------------------------------------------------------------------------------- /docs/images/AudioSource_OutputHighlighted.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/AudioSource_OutputHighlighted.png -------------------------------------------------------------------------------- /docs/images/PlayerPrefab_PositionalAudio.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/PlayerPrefab_PositionalAudio.png -------------------------------------------------------------------------------- /docs/images/PlayerProximityChat_Inspector.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/PlayerProximityChat_Inspector.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Default.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Default.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Player.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Player.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Targets.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Targets.png -------------------------------------------------------------------------------- /docs/images/VoiceReceiptTrigger_LobbyRoom.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceReceiptTrigger_LobbyRoom.png -------------------------------------------------------------------------------- /docs/images/VoiceReceiptTrigger_Overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceReceiptTrigger_Overview.png -------------------------------------------------------------------------------- /docs/images/PlaybackPrefab_OutputHighlighted.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/PlaybackPrefab_OutputHighlighted.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_LobbyRoom.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_LobbyRoom.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Overview.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Positional.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Positional.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Priority.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Priority.png -------------------------------------------------------------------------------- /docs/images/AudioSource_SpatializeHighlighted.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/AudioSource_SpatializeHighlighted.png -------------------------------------------------------------------------------- /docs/images/ProximityReceiptTrigger_Inspector.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/ProximityReceiptTrigger_Inspector.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_DifferentPTT.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_DifferentPTT.png -------------------------------------------------------------------------------- /docs/images/ProximityBroadcastTrigger_Inspector.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/ProximityBroadcastTrigger_Inspector.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger-AmplitudeFaders.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger-AmplitudeFaders.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_SectionsOverview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_SectionsOverview.png -------------------------------------------------------------------------------- /docs/css/pygment_tweaks.css: -------------------------------------------------------------------------------- 1 | .codehilite { 2 | outline: 1px solid rgba(0,0,0,0.35); 3 | margin: 5px; 4 | padding: 0.5em; 5 | } 6 | 7 | .codehilite pre { 8 | margin: 0; 9 | } -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Section_AccessTokens.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Section_AccessTokens.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Section_ChannelType.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Section_ChannelType.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Section_ActivationMode.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Section_ActivationMode.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Section_AmplitudeFaders.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Section_AmplitudeFaders.png -------------------------------------------------------------------------------- /docs/images/VoiceBroadcastTrigger_Section_ChannelMetadata.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Placeholder-Software/Dissonance/HEAD/docs/images/VoiceBroadcastTrigger_Section_ChannelMetadata.png -------------------------------------------------------------------------------- /docs/css/header_tweaks.css: -------------------------------------------------------------------------------- 1 | /* h2 { 2 | color: var(--md-primary-fg-color) 3 | } 4 | 5 | h3 { 6 | color: var(--md-primary-fg-color) 7 | } 8 | 9 | h4 { 10 | color: var(--md-primary-fg-color) 11 | } */ -------------------------------------------------------------------------------- /docs/Platforms/Windows UWP & Hololens.md: -------------------------------------------------------------------------------- 1 | # Windows (UWP/Hololens) 2 | 3 | To run Dissonance on a Windows PC within a UWP application requires [Visual Studio 2017 v141 Redist](https://www.visualstudio.com/downloads/#title-90c66ddff7b7862f11eca8ffc80762c5). It's recommended that you package this with your application and install it as part of your install process. -------------------------------------------------------------------------------- /docs/Tutorials/Spatializer-Plugin.md: -------------------------------------------------------------------------------- 1 | Since [Dissonance 7.0.2](https://placeholder-software.co.uk/dissonance/releases/7.0.2.html) Dissonance no longer supports external spatialization plugins. A change in how Unity applies spatialization has made support for this feature impossible. Unity have acknowledged this bug and we will add support back into Dissonance as soon as possible. -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: ci 2 | on: 3 | push: 4 | branches: 5 | - master 6 | jobs: 7 | deploy: 8 | runs-on: ubuntu-latest 9 | steps: 10 | - uses: actions/checkout@v3 11 | - uses: actions/setup-python@v2 12 | with: 13 | python-version: 3.x 14 | - run: pip install mkdocs-material 15 | - run: mkdocs gh-deploy --force -------------------------------------------------------------------------------- /docs/Basics/Licensing.md: -------------------------------------------------------------------------------- 1 | Dissonance uses some open source libraries to provide audio preprocessing, postprocessing, encoding and decoding. The distribution requirements for the projects used are all very simple - you must include copies of the license files in distributions of your project. 2 | 3 | - [Opus License](https://opus-codec.org/license/) 4 | - [WebRTC License](https://webrtc.org/support/license/) 5 | - [RNNoise License](https://github.com/xiph/rnnoise/blob/master/COPYING) -------------------------------------------------------------------------------- /docs/Platforms/Oculus OVR.md: -------------------------------------------------------------------------------- 1 | # Oculus OVR 2 | 3 | If you are using the [Oculus OVR SDK](https://assetstore.unity.com/packages/tools/integration/oculus-integration-82022) you must disable the `Ovr Avatar` component from taking exclusive control of the microphone (which prevents Dissonance from using it). 4 | 5 | ![OVR Local Avatar](../images/OVR Local Avatar.png "OVR Local Avatar") 6 | 7 | 1. Locate the `LocalAvatar` GameObject 8 | 2. Unchecked `Can Own Microphone` in the inspector for the `Ovr Avatar` component -------------------------------------------------------------------------------- /docs/javascript/redirector.js: -------------------------------------------------------------------------------- 1 | if (window.location.host == "dissonance.readthedocs.io") { 2 | 3 | // RTD style links are: dissonance.readthedocs.io/en/latest/some/page 4 | // This needs to be rewritten into: https://placeholder-software.co.uk/dissonance/docs/some/page 5 | 6 | var path = window.location.pathname; 7 | if (path.startsWith("/en/latest")) { 8 | path = path.substring(10); 9 | } 10 | 11 | window.location.replace("https://placeholder-software.co.uk/dissonance/docs" + path) 12 | } -------------------------------------------------------------------------------- /docs/Reference/Other/TextChat.md: -------------------------------------------------------------------------------- 1 | # TextChat 2 | 3 | This object exposes properties and method to do with text chat within a Dissonance session. 4 | 5 | ### Send(string, string) 6 | 7 | Send a message to the given room. 8 | 9 | ### Whisper(string, string) 10 | 11 | Send a message to the given player. 12 | 13 | ### MessageReceived : event Action 14 | 15 | An event which indicates a text message was received from another player. The `TextMessage` object contains information about who send the message, how they sent it and what the message is. -------------------------------------------------------------------------------- /docs/Platforms/Magic Leap.md: -------------------------------------------------------------------------------- 1 | # Magic Leap 2 | 3 | Dissonance includes support for LuminOS on Magic leap devices. To enable this you must change the import settings of `Assets\Plugins\Dissonance\Plugins\Magic Leap\libAudioPluginDissonance.so` and `Assets\Plugins\Dissonance\Plugins\Android\libs\ARM64\libopus.so` to be included in Magic Leap builds. 4 | 5 | *Acoustic Echo Cancellation* (AEC) and *Noise Suppression* (NS) are built into the magic leap device. To prevent interference the Dissonance AEC and NS systems are disabled when deployed to a Magic Leap headset, any configuration settings in Dissonance for these two systems will be ignored. -------------------------------------------------------------------------------- /Readme.md: -------------------------------------------------------------------------------- 1 | ## Dissonance - Unity Voice Chat Asset 2 | 3 | Dissonance is a drop in voice chat asset for multiplayer games built in unity. This repository does *not* contain the source code for Dissonance, it is used to host documentation and issue tracking. 4 | 5 | - [Homepage](https://placeholder-software.co.uk/dissonance) 6 | - [Unity Store](https://assetstore.unity.com/packages/slug/70078?aid=1100lJDF) 7 | - [Documentation](https://placeholder-software.co.uk/dissonance/docs/) 8 | - [Issue Tracker](https://github.com/Placeholder-Software/Dissonance/issues) 9 | - [Discussion Forum](https://www.reddit.com/r/dissonance_voip) 10 | - [Discord Server](https://discord.gg/8dKpP5W) 11 | -------------------------------------------------------------------------------- /docs/Platforms/Windows Desktop.md: -------------------------------------------------------------------------------- 1 | # Windows (Desktop) 2 | 3 | To run Dissonance on a Windows PC requires [Visual Studio **Redistributable**](https://aka.ms/vs/17/release/vc_redist.x64.exe). 4 | 5 | On systems older than Windows 10, users must also install [this](https://support.microsoft.com/en-us/topic/update-for-universal-c-runtime-in-windows-c0514201-7fe6-95a3-b0a5-287930f3560c) Windows Update. 6 | 7 | ## Steam 8 | 9 | If you are distributing your application through [Steam](https://store.steampowered.com/) you can set the redistributable as a dependency. It will be installed when the application is installed. This can be done through the [app panel](partner.steamgames.com): `App Panel > Installation > Redistributables > Visual C++ Redist 2019`. 10 | -------------------------------------------------------------------------------- /docs/Reference/Other/Rooms.md: -------------------------------------------------------------------------------- 1 | # Rooms 2 | 3 | This object exposes properties and method to do with rooms that the local player is *listening* to. For rooms the player is speaking to see [this documentation](../Other/RoomChannels.md) intead. 4 | 5 | ### Count : int 6 | 7 | The number of rooms which the local player is a listening to. 8 | 9 | ### Contains(string) : bool 10 | 11 | Returns a boolean value indicating if the local player is listening to a room with the given name. 12 | 13 | ### Join(string) : RoomMembership 14 | 15 | Begin listening to the room with the given name. Returns a "RoomMembership" object which can be used to stop listening to the room. 16 | 17 | ### Leave(RoomMembership) : bool 18 | 19 | Stop listening to the room represented by the given RoomMembership. -------------------------------------------------------------------------------- /docs/Tutorials/Global-Chat-Room.md: -------------------------------------------------------------------------------- 1 | A global chat room is just a single room which all users talk to and listen to. This is a very simple system to create using Dissonance. 2 | 3 | ![Example of inspector for a single global chat room](../images/GlobalChatRoom_Inspector.png "Example of inspector for a single global chat room") 4 | 5 | 1. Create a Voice Broadcast Trigger and a Voice Receipt Trigger on the root Dissonance game object 6 | 2. Set the room for both of them to "Global". 7 | 8 | Both components will activate when the scene loads (on each different computer in the network session) and all players will be in the room. 9 | 10 | Find out more about the [broadcast trigger](../Reference/Components/Voice-Broadcast-Trigger.md) and the [receipt trigger](../Reference/Components/Voice-Receipt-Trigger.md). -------------------------------------------------------------------------------- /docs/Platforms/iOS.md: -------------------------------------------------------------------------------- 1 | # iOS 2 | 3 | Running Dissonance on iOS has no runtime dependencies. 4 | 5 | In the [Player Settings for iOS](https://docs.unity3d.com/Manual/class-PlayerSettingsiOS.html) there are four settings relevant to voice chat: 6 | 7 | - `Microphone Usage Description`: You ***must*** enter the reason for accessing the microphone on the iOS device. 8 | - `Prepare iOS for Recording`: You ***must*** enable this setting to enable low latency audio recording. 9 | 10 | --- 11 | 12 | - `Mute Other Audio Sources`: You ***may*** enable this to ensure that background audio does not interfere with voice audio. 13 | - `Force iOS Speakers when Recording`: You ***may*** enable this to force audio to the speakers even when headphones are plugged in. If this is not enabled _all_ application audio will be played through the call speakers instead of the main speakers as soon as recording starts. -------------------------------------------------------------------------------- /docs/Platforms/Android.md: -------------------------------------------------------------------------------- 1 | # Android (Including Oculus Quest) 2 | 3 | On Android the user must grant permission before the Microphone is accessed. Since Dissonance uses the Unity `Microphone` class the `Record_Audio` permission should have already been added to the [app manifest](https://docs.unity3d.com/Manual/android-manifest.html). When the application is started the user is asked for all of the permissions in the manifest in one dialog. 4 | 5 | If `Microphone` permission is not granted when Dissonance is started it will operate in listen-only mode. 6 | 7 | The [Runtime Permission System](https://docs.unity3d.com/Manual/android-RequestingPermissions.html) may be be used to request permission from the user again at any time. If permission is granted after Dissonance has already started you should call [DissonanceComms.ResetMicrophoneCapture](../Reference/Components/Dissonance-Comms.md#resetmicrophonecapture) to restart the microphone recording system. -------------------------------------------------------------------------------- /docs/Reference/Components/Voice-Receipt-Trigger.md: -------------------------------------------------------------------------------- 1 | # Voice Receipt Trigger 2 | 3 | The Voice Receipt Trigger controls which rooms are being listened to by the local player. 4 | 5 | ![Voice Receipt Trigger Inspector](../../images/VoiceReceiptTrigger_Overview.png "Voice Receipt Trigger Inspector") 6 | 7 | ## Trigger Activation 8 | 9 | This determines whether the receiver will only receive when the local player is within a trigger zone. See the Unity documentation on [Trigger Zones](https://unity3d.com/learn/tutorials/topics/physics/colliders-triggers). Using trigger activation requires the same basic setup as using [Positional Audio](../../Tutorials/Position-Tracking.md). This setting can be configured from a script by modifying the `UseTrigger` field. 10 | 11 | ## Chat Room 12 | 13 | Determines which room this receiver is for. Available rooms are listed in a dropdown box and new rooms may be added by clicking the "Config Rooms" button. The target room name can be configured from a script by modifying the `RoomName` field. -------------------------------------------------------------------------------- /docs/Reference/Other/PlayerChannels.md: -------------------------------------------------------------------------------- 1 | # PlayerChannels 2 | 3 | This object exposes properties and methods to do with players that the local player is *speaking* to. 4 | 5 | ### Count : int 6 | 7 | The number of players which the local player is a speaking to. 8 | 9 | ### Contains(PlayerChannel) : bool 10 | 11 | Returns a boolean value indicating if the local player is speaking to the given channel. 12 | 13 | ### Open(string, [bool], [ChannelPriority], [float]) : PlayerChannel 14 | 15 | Opens a channel to begin speaking to the given player and returns a [PlayerChannel](../Other/PlayerChannel.md) object which represents this open channel (and can be used to close it). 16 | 17 | Takes three optional parameters. 18 | 1. A boolean value indicating if this channel should use positional playback 19 | 2. A ChannelPriority which indicates the priority of this channel 20 | 3. A float which indicates the volume to play back this channel with 21 | 22 | ### Close(PlayerChannel) : bool 23 | 24 | Closes the given channel and returns a boolean indicating if the channel was open in the first place. -------------------------------------------------------------------------------- /docs/Platforms/MacOS.md: -------------------------------------------------------------------------------- 1 | # MacOS 2 | 3 | Running Dissonance on MacOS has no runtime dependencies. 4 | 5 | # Permission 6 | 7 | To record audio a MacOS app requires permission from the user. See the Unity docs [here](https://docs.unity3d.com/ScriptReference/Application.RequestUserAuthorization.html) and the Apple docs [here](https://developer.apple.com/documentation/avfoundation/cameras_and_media_capture/requesting_authorization_for_media_capture_on_macos) on how to request permission. 8 | 9 | # Notarization 10 | 11 | All applications running on MacOS Catalina 10.15 require "notarization". See the Apple docs [here](https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution) and a tutorial on permissions and notarization for Unity apps [here](https://gist.github.com/dpid/270bdb6c1011fe07211edf431b2d0fe4). 12 | 13 | To access the microphone you will need to add two keys to the entitlements file: 14 | 15 | - com.apple.security.device.audio-input 16 | - com.apple.security.device.microphone 17 | 18 | You may need to add other keys to enable access to networking. -------------------------------------------------------------------------------- /docs/Reference/Other/RoomChannels.md: -------------------------------------------------------------------------------- 1 | # RoomChannels 2 | 3 | This object exposes properties and method to do with rooms that the local player is *speaking* to. For rooms the player is listening to see [this documentation](../Other/Rooms.md) intead. 4 | 5 | ### Count : int 6 | 7 | The number of rooms which the local player is a speaking to. 8 | 9 | ### Contains(RoomChannel) : bool 10 | 11 | Returns a boolean value indicating if the local player is speaking to the given channel. 12 | 13 | ### Open(string, [bool], [ChannelPriority], [float]) : RoomChannel 14 | 15 | Opens a channel to begin speaking to the given room and returns a [RoomChannel](../Other/RoomChannel.md) which represents this open channel (and can be used to close it). 16 | 17 | Takes three optional parameters. 18 | 1. A boolean value indicating if this channel should use positional playback 19 | 2. A ChannelPriority which indicates the priority of this channel 20 | 3. A float which indicates the volume to play back this channel with 21 | 22 | ### Close(RoomChannel) : bool 23 | 24 | Closes the given channel and returns a boolean indicating if the channel was open in the first place. -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | ## Dissonance VoIP 2 | 3 | [Dissonance](https://placeholder-software.co.uk/dissonance/) is a realtime Voice over IP (VoIP) system designed to be built directly into Unity games. 4 | 5 | - Low latency/real-time voice communications. 6 | - Compact Opus encoding. 7 | - Multiple chat rooms. 8 | - Private messages to individual players. 9 | - Voice Activation and Push To Talk. 10 | - Positional Audio. 11 | - Echo cancellation. 12 | - Flexible Networking. 13 | 14 | ## Getting Started 15 | 16 | The [**Project Setup**](Basics/Getting-Started.md) will guide you through importing Dissonance into your project and then present you with links to tutorials. 17 | 18 | ## Intermediate Topics 19 | 20 | These tutorials are intended for after you understand how to use the basic core features of Dissonance, they will guide you on how to get the most out of voice communication for your game. 21 | 22 | ## Advanced Topics 23 | 24 | If you want to do something unusual with Dissonance the advanced tutorials are the place to start. However we can't cover everything so if what you want to achieve isn't covered try [asking the community](https://www.reddit.com/r/dissonance_voip) or [reporting an issue](https://github.com/Placeholder-Software/Dissonance). -------------------------------------------------------------------------------- /docs/Tutorials/Push-to-Talk.md: -------------------------------------------------------------------------------- 1 | !!! Video Tutorial 2 | See [this video](https://www.youtube.com/watch?v=Kz7qM6XditI) about push to talk activation. 3 | 4 | When a broadcast trigger is in Push-To-Talk (PTT) mode voice will only be transmitted while the "talk" button is pressed. 5 | 6 | To set a broadcast trigger to use PTT simply change the "Activation Mode" to "Push To Talk" and choose which input axis must be pressed for voice to be transmitted. See the [Unity documentation](https://docs.unity3d.com/Manual/class-InputManager.html) for how to define a new input axis. 7 | 8 | ![A Voice Broadcast Trigger with Push To Talk](../images/VoiceBroadcastTrigger_PTT.png) 9 | 10 | ## UI Button 11 | 12 | Instead of using an input axis you may want to trigger push-to-talk from a UI button. 13 | 14 | 1. Set the `Activation Mode` to `Open`. This constantly transmits voice. 15 | 2. Set `Mute` to `true`. This prevents any voice from being transmitted. 16 | 3. Configure your UI button to trigger the `ToggleMute` method. This inverts the `Mute` setting each time it is called. 17 | 18 | With this setup clicking the UI button once will unmute the trigger and speech will be transmitted, clicking the button again will mute the trigger and stop speech from being transmitted. -------------------------------------------------------------------------------- /docs/Tutorials/UsingIMicrophoneSubscriber.md: -------------------------------------------------------------------------------- 1 | ## Direct Access To Recorded Audio 2 | 3 | Dissonance includes a mechanism for directly accessing the stream of recorded audio, this can be used to drive features such as recording the mic input to file or passing it through a Speech-To-Text system. 4 | 5 | There are two ways to implement this, direct low-level access through [IMicrophoneSubscriber](../Reference/Audio/IMicrophoneSubscriber.md) and easier access through [BaseMicrophoneSubscriber](../Reference/Audio/BaseMicrophoneSubscriber.md). 6 | 7 | Once you have created a script which uses either of these systems you must register it to receive data from Dissonance by calling `FindObjectOfType().SubscribeToRecordedAudio(your_script)` and passing in your script as `your_script`. 8 | 9 | ### BaseMicrophoneSubscriber 10 | 11 | This provides easy access to the microphone audio stream. This script handles capturing and buffering the data, it is delivered in batches on the main thread. 12 | 13 | ### IMicrophoneSubscriber 14 | 15 | This provides direct access to the microphone audio stream as directly as possible. Audio is delivered to the `ReceiveMicrophoneData` method on the background audio processing thread **not** the main thread. Only use this if `BaseMicrophoneProvider` does not meet your use case! -------------------------------------------------------------------------------- /docs/Reference/Components/Voice-Proximity-Receipt-Trigger.md: -------------------------------------------------------------------------------- 1 | # Voice Proximity Receipt Trigger 2 | 3 | The Voice Proximity Receipt Trigger receives voice to an infinite grid of "virtual rooms", creating a proximity chat system by placing nearby players into the same rooms. 4 | 5 | ![Voice Proximity Receipt Trigger Inspector](../../images/ProximityReceiptTrigger_Inspector.png "Voice Proximity Receipt Trigger Inspector") 6 | 7 | ## Room 8 | 9 | This section controls which room the trigger receives from. 10 | 11 | #### Chat Room 12 | 13 | It is possible to have several proximity broadcast systems running simultaneously (e.g. one per team), the room name uniquely identifies this room. 14 | 15 | #### Range 16 | 17 | Set the distance to receive voice, players within this distance will be considered "near" and will be placed into the same room. 18 | 19 | !!! hint 20 | The range must be exactly the same for the broadcast trigger and the receipt trigger! 21 | 22 | ## Access Tokens 23 | 24 | Add [Access Tokens](../../Tutorials/Access-Control-Tokens.md) which are required for this broadcaster to broadcast voice. This trigger will only receive if the DissonanceComms component has one or more of the necessary tokens. 25 | 26 | #### Collider Activation 27 | 28 | Only receive when the local player is inside a sibling collider volume. -------------------------------------------------------------------------------- /docs/Tutorials/Direct-Player-Transmit.md: -------------------------------------------------------------------------------- 1 | !!! Video Tutorial 2 | See [this video](https://youtu.be/HXMYDbuLwVI?t=1064) about direct player messaging. 3 | 4 | This tutorial will explain how to broadcast a voice message directly to a specific player, rather than to all players in a room. There are two ways to achieve this. 5 | 6 | ## Set The Player Name 7 | 8 | To transmit to a specific player, change the Channel Type option on the `VoiceBroadcastTrigger` to "Player", then give the player name for Recipient Player Name. 9 | 10 | ![Broadcast Trigger configured for player messaging](../images/VoiceBroadcastTrigger_Player.png) 11 | 12 | To change the targetted player at run time modify the `PlayerId` field of the `VoiceBroadcastTrigger` behaviour. 13 | 14 | ```csharp 15 | GetComponent().PlayerId = "TheNewRemotePlayerName"; 16 | ``` 17 | 18 | ## Target A Player Behaviour 19 | 20 | If you have set up Dissonance [position tracking](Position-Tracking.md) in your game then the game objects which represent your players will all have a behaviour on them which implements the `IDissonancePlayer` interface. For example if you are using the Forge Networking integration this is the `ForgePlayer` component. 21 | 22 | To transmit to this player change the Channel Type option on a `VoiceBroadcastTrigger` attached to the same game object to "Self". 23 | 24 | ![Broadcast Trigger configured for alternative player messaging](../images/BroadcastToSelf_Inspector.png) -------------------------------------------------------------------------------- /docs/Reference/Audio/BaseMicrophoneSubscriber.md: -------------------------------------------------------------------------------- 1 | # BaseMicrophoneSubscriber 2 | 3 | This script makes it easier to directly access the recorded audio data. All methods on this script are called on the main thread. 4 | 5 | Implement a new script with `BaseMicrophoneSubscriber` as the base class instead of `MonoBehaviour`, once you have done this register an instance of the behaviour to receive data by calling `DissonanceComms.SubscribeToRecordedAudio`. 6 | 7 | See also [IMicrophoneSubscriber](IMicrophoneSubscriber.md) which does not have any of the ease-of-use features of this script, providing more direct access. 8 | 9 | ### ResetAudioStream(WaveFormat waveFormat) 10 | 11 | This method is called by Dissonance whenever the audio stream is being reset, or the audio format is changing. The `waveFormat` argument indicates the format of the next data which will be delivered. 12 | 13 | When this is called you should immediately finish any work you were doing with the audio and prepare for more audio to be delivered soon. For example if you are recording audio to a file you would flush the file writer and close the file handle. 14 | 15 | ### ProcessAudio(ArraySegment data) 16 | 17 | This method is called by Dissonance for every frame of recorded audio data. The `data` argument contains raw PCM audio data. 18 | 19 | After this method has finished executing you **must not** hold any references to the `data` argument. Any data that you want to store for processing later must be copied out of the `data`. -------------------------------------------------------------------------------- /docs/Tutorials/Player-State.md: -------------------------------------------------------------------------------- 1 | Dissonance offers an easy to use API for finding out information about other players in the session. 2 | 3 | ## Discovering Players 4 | 5 | There are two ways to discover who is in the Dissonance session - events and polling. To get a list of players currently in the session, you can access the `Players` property on the DissonanceComms object: 6 | 7 | ```csharp 8 | var comms = FindObjectOfType(); 9 | foreach (var player in comms.Players) 10 | { 11 | Debug.Log("Player " + player.Name + " is in the game"); 12 | } 13 | ``` 14 | 15 | This will give you a set of [VoicePlayerState](../Reference/Other/VoicePlayerState.md) objects (including one for the local player). These objects will stay valid forever and will be updated with new information as necessary. 16 | 17 | Dissonance also exposes some events which will get invoked when certain things happen, for example a new player joining the session. 18 | 19 | ```csharp 20 | var comms = FindObjectOfType(); 21 | comms.OnPlayerJoinedSession += player => { 22 | Debug.Log("Player " + player.Name + " Joined session"); 23 | } 24 | 25 | comms.OnPlayerLeftSession += player => { 26 | Debug.Log("Player " + player.Name + " Left session"); 27 | } 28 | ``` 29 | 30 | The `player` objects passed to the event handlers here are [VoicePlayerState](../Reference/Other/VoicePlayerState.md) objects which expose a lot of useful data about the players such as if they are currently talking and a live readout of the amplitue. -------------------------------------------------------------------------------- /docs/Reference/Other/RemoteChannel.md: -------------------------------------------------------------------------------- 1 | # RemoteChannel 2 | 3 | A `RemoteChannel` struct represents a snapshot of information about a channel which a player is speaking through. 4 | 5 | ## Read Only Properties 6 | 7 | ### Type : ChannelType 8 | 9 | Get the type of this channel. A channel is either to a Room (in which case the local player will only hear voices if they are subscribed to the Room) or to a player (in which case the appropriate player will hear the voice without needing to subscribe to it). 10 | 11 | ### Options : PlaybackOptions 12 | 13 | Get the `PlaybackOptions` which have been set for this channel. The actual playback options used are an aggregation of the options set on all the channels the local player is receiving voice from the given player through. 14 | 15 | #### Options.IsPositional : bool 16 | 17 | Get whether this channel should be played with positional audio. Actual audio playback will be positional only if *all* channels from the given player are set to positional playback. 18 | 19 | #### Options.AmplitudeMultiplier : float 20 | 21 | Get the amplitude multiplier to apply to audio through this channel. The _maximum_ multiplier from all channels from the given player will be used. 22 | 23 | #### Options.Priority : ChannelPriority 24 | 25 | Get the priority of audio through this channel. The _maximum_ priority from all channels from the given player will be used. 26 | 27 | ### TargetName : string 28 | 29 | Get the name of the target of this channel. This is either a room name or a player name, depending upon the `Type` property. -------------------------------------------------------------------------------- /docs/Reference/Audio/IMicrophoneSubscriber.md: -------------------------------------------------------------------------------- 1 | # IMicrophoneSubscriber 2 | 3 | This interface allows a script to be added into the Dissonance audio recording pipeline, giving you direct access to the audio data. 4 | 5 | Once you have implemented the `IMicrophoneSubscriber` on a class you can register an instance of the class to receive data by calling `DissonanceComms.SubscribeToRecordedAudio`. See [this tutorial](../../Tutorials/UsingIMicrophoneSubscriber.md) for more information. 6 | 7 | The methods on this interface are automatically called by Dissonance, they **are not called on the main thread**. You must be careful in implementations of this interface to handle 8 | 9 | See also [BaseMicrophoneSubscriber](BaseMicrophoneSubscriber.md) which implements this interface in an more convenient package. 10 | 11 | ### Reset 12 | 13 | This method is called by Dissonance whenever the audio pipeline is being reset. When this is called you should immediately finish any work you were doing with the audio and prepare for more audio to be delivered soon. For example if you are recording audio to a file you would flush the file writer and close the file handle. 14 | 15 | ### ReceiveMicrophoneData 16 | 17 | This method is called by Dissonance for every frame of recorded audio data. The `buffer` argument contains raw PCM audio data. The `format` argument indicates the format of the data in the buffer, this will only change after `Reset` has been called. 18 | 19 | After this method has finished executing you **must not** hold any references to the `buffer` argument. Any data that you want to store for processing later must be copied out of the `buffer`. -------------------------------------------------------------------------------- /docs/Tutorials/Text-Chat.md: -------------------------------------------------------------------------------- 1 | Dissonance allows text chat messages to be routed through the network to the same players and chat rooms used by voice. This tutorial will demonstrate the APIs provided to send and receive text chat messages with Dissonance. 2 | 3 | ## Send a text message to a Chat Room 4 | 5 | ```csharp 6 | // get the DissonanceComms script from the Dissonance game object 7 | var dissonance = GetComponent(); 8 | 9 | // send a text message to the Party chat channel 10 | dissonance.Text.Send("Party", "Who just pulled the boss?") 11 | ``` 12 | 13 | ## Send a text message to a player 14 | 15 | ```csharp 16 | // get the DissonanceComms script from the Dissonance game object 17 | var dissonance = GetComponent(); 18 | 19 | // send a text message to a specific player 20 | dissonance.Text.Whisper("hunter", "Did you just pull the boss?") 21 | ``` 22 | 23 | ## Receive a text message 24 | 25 | Dissonance will only send you text messages if they are directly addressed to you or to a room which you are listening to. To listen to a room you can use a voice receipt trigger [voice receipt trigger](../Reference/Components/Voice-Receipt-Trigger.md), or directly use the Dissonance API from scripts to enter the room. 26 | 27 | ```csharp 28 | // get the DissonanceComms script from the Dissonance game object 29 | var dissonance = GetComponent(); 30 | 31 | //If necessary, enter a room using the scripting API 32 | dissonance.Rooms.Join("Room Name"); 33 | 34 | dissonance.Text.MessageRecieved += message => { 35 | 36 | //This code will run every time you receive a text message 37 | 38 | var format = "[{0}] {1}: {2}"; 39 | if (message.RecipientType == ChannelType.Player) 40 | format = "{1} whispers: {2}"; 41 | 42 | chatLog.Write(string.Format(format, message.Recipient, message.Sender, message.Message)); 43 | }; 44 | ``` -------------------------------------------------------------------------------- /docs/Reference/Other/RoomChannel.md: -------------------------------------------------------------------------------- 1 | # RoomChannel 2 | 3 | This object represents a single speech channel to a room opened with the [PlayerChannels](../Other/PlayerChannels.md) API. Other players will only receive the voice if they have joined the room. 4 | 5 | ### Dispose() 6 | 7 | Closes this channel. 8 | 9 | ### SubscriptionId : ushort 10 | 11 | Get the unique ID of this channel. This is only unique among the set of open channels - once this channel is closed the ID may be re-used by another channel. 12 | 13 | ### TargetId : string 14 | 15 | Get the name of the room this channel is sending voice to. 16 | 17 | ### IsOpen : bool 18 | 19 | Get a value indicating if this channel is currently open. Once a channel is closed you should release the channel struct - it is useless (re-opening the channel will create a new PlayerChannel struct). 20 | 21 | Once IsOpen becomes false then accessing most other properties will immediately throw an exception. 22 | 23 | ### Positional : bool 24 | 25 | Get or set whether audio sent through this channel should use positional playback. 26 | 27 | If there are multiple channels open sending the same voice then playback will only be positional if *all* channels are set to use positional playback. 28 | 29 | ### Priority : ChannelPriority 30 | 31 | Get or set the priority of voice sent with this channel. 32 | 33 | If priority is set to `None` then it will fall back to using the priority set on the local DissonanceComms component in the `PlayerPriority` property. 34 | 35 | If there are multiple channels open sending the same voice data then playback will use the highest priority. 36 | 37 | ### Volume : float 38 | 39 | Get or set the volume to play back the voice sent through this channel. Volume is a direct multiplier on the audio data and should be between 0 and 1. 40 | 41 | If there are multiple channels open sending the same voice then playback will use the loudest volume. -------------------------------------------------------------------------------- /docs/Reference/Other/PlayerChannel.md: -------------------------------------------------------------------------------- 1 | # PlayerChannel 2 | 3 | This object represents a single speech channel directly to another player opened with the [PlayerChannels](../Other/PlayerChannels.md) API. The other player will receive the local voice without having to take any action. 4 | 5 | ### Dispose() 6 | 7 | Closes this channel. 8 | 9 | ### SubscriptionId : ushort 10 | 11 | Get the unique ID of this channel. This is only unique among the set of open channels - once this channel is closed the ID may be re-used by another channel. 12 | 13 | ### TargetId : string 14 | 15 | Get the name of the player this channel is sending voice to. 16 | 17 | ### IsOpen : bool 18 | 19 | Get a value indicating if this channel is currently open. Once a channel is closed you should release the channel struct - it is useless (re-opening the channel will create a new PlayerChannel struct). 20 | 21 | Once IsOpen becomes false then accessing most other properties will immediately throw an exception. 22 | 23 | ### Positional : bool 24 | 25 | Get or set whether audio sent through this channel should use positional playback. 26 | 27 | If there are multiple channels open sending the same voice then playback will only be positional if *all* channels are set to use positional playback. 28 | 29 | ### Priority : ChannelPriority 30 | 31 | Get or set the priority of voice sent with this channel. 32 | 33 | If priority is set to `None` then it will fall back to using the priority set on the local DissonanceComms component in the `PlayerPriority` property. 34 | 35 | If there are multiple channels open sending the same voice data then playback will use the highest priority. 36 | 37 | ### Volume : float 38 | 39 | Get or set the volume to play back the voice sent through this channel. Volume is a direct multiplier on the audio data and should be between 0 and 1. 40 | 41 | If there are multiple channels open sending the same voice then playback will use the loudest volume. -------------------------------------------------------------------------------- /docs/Tutorials/Channel-Priority.md: -------------------------------------------------------------------------------- 1 | Channel priority can be used to automatically mute low priority channels while high priority channels are speaking. For example muting the global voice chat room whilst someone in the team chat room is talking. 2 | 3 | ## Priority Levels 4 | 5 | There are 4 priority levels which can be set on a channel: 6 | 7 | 1. Low 8 | 2. Default 9 | 3. Medium 10 | 4. High 11 | 12 | If a player is receiving voice from multiple sources then the sources with the highest priority will play and all others will be muted. 13 | 14 | There is another priority option: `None`. If this used then the priority falls back to the default value for this player, which is set in `DissonanceComms.PlayerPriority`. If `None` is specified as the default player priority then `Default` is used instead. 15 | 16 | ## Defining Priority 17 | 18 | The priority of a channel can be defined in a number of ways. The inspector for the Voice Broadcast Trigger allows you to set the priority for voice sent with this trigger: 19 | 20 | ![Receipt Trigger](../images/VoiceBroadcastTrigger_Priority.png) 21 | 22 | In scripts you can change the priority for a VoiceBroadcastTrigger with the `Priority` property: 23 | 24 | ```csharp 25 | var trigger = GetComponent(); 26 | 27 | trigger.Priority = ChannelPriority.High; 28 | ``` 29 | 30 | Alternatively if you are [directly using channels](Directly-Using-Channels.md) from scripts instead of using the trigger components you can set the priority when the channel is created, and then modify it from the channel object at any time: 31 | 32 | ```csharp 33 | var comms = GetComponent(); 34 | 35 | //Create the channel with an explicit priority 36 | var channel = comms.RoomChannels.Open("Room Name", priority: ChannelPriority.High); 37 | 38 | //Change the priority 39 | channel.Priority = ChannelPriority.Medium; 40 | 41 | //Close the channel 42 | channel.Dispose(); 43 | ``` -------------------------------------------------------------------------------- /docs/Basics/Other-Integrations.md: -------------------------------------------------------------------------------- 1 | Dissonance has optional integrations with some non-networking assets to add/improve certain features. 2 | 3 | ## SALSA Lip Sync 4 | 5 | [SALSA Lip Sync](https://assetstore.unity.com/packages/tools/animation/salsa-lipsync-suite-148442?aid=1100lJDF) provides real-time lip synchronisation. The `SalsaDissonanceLink` integration connects the Dissonance audio system to the lip sync system to provide real-time lip synchronisation for other speakers in the VoIP session. 6 | 7 | For a download link and more information, see the [full documentation](https://crazyminnowstudio.com/docs/salsa-lip-sync/addons/using-with-dissonance/) on the SALSA docs. 8 | 9 | ## [FMOD Playback](https://assetstore.unity.com/packages/slug/213415?aid=1100lJDF) 10 | 11 | [FMOD](https://assetstore.unity.com/packages/tools/audio/fmod-for-unity-161631?aid=1100lJDF) is a powerful alternative audio system for Unity. The [FMOD Playback](https://assetstore.unity.com/packages/slug/213415?aid=1100lJDF) integration package outputs Dissonance audio into the FMOD audio system. This allows you to mix Dissonance audio in the FMOD mixer and to completely disable the Unity audio system. 12 | 13 | !!! important "" 14 | If you completely disable the Unity audio system you **must** also use the FMOD Recording package. 15 | 16 | ## [FMOD Recording](https://assetstore.unity.com/packages/slug/213412?aid=1100lJDF) 17 | 18 | [FMOD](https://assetstore.unity.com/packages/tools/audio/fmod-for-unity-161631?aid=1100lJDF) is a powerful alternative audio system for Unity. The [FMOD Recording](https://assetstore.unity.com/packages/slug/213412?aid=1100lJDF) integration package provides higher quality and lower latency audio to Dissonance through FMOD. 19 | 20 | !!! important "" 21 | Using this integration does **not** require that you are using FMOD for audio playback. You can install FMOD just for the higher quality audio recording and continue to use the normal Unity audio systems. -------------------------------------------------------------------------------- /docs/Tutorials/Team-Chat-Rooms.md: -------------------------------------------------------------------------------- 1 | A team chat room is a set of rooms where all users *on the same team* talk to and listen to the same room. To create a setup like this requires a small amount of scripting as it depends on how your game defines what a "team" actually is! 2 | 3 | To create a team chat setup first create multiple pairs of broadcasters and receivers, one for each team. 4 | 5 | ![Example of team chat configuration](../images/TeamChat_Inspector.png) 6 | 7 | With the setup as shown here every player will speak and and listen to every team channel. To fix this add a unique token to each pair of triggers (e.g. the team name), once you have done this none of the triggers will activate and no one will speak or listen to any of the team rooms. 8 | 9 | Finally, when you create a player and assign them to a team run a script which adds the appropriate token to the local player. Exactly how this code works depends a lot on exactly how your game defines what a team is, feel free to [ask for help](https://www.reddit.com/r/dissonance_voip/). Here is some example code: 10 | 11 | ```csharp 12 | void OnAssignPlayerToTeam(string teamName) 13 | { 14 | //Find local comms object 15 | var comms = FindObjectOfType(); 16 | 17 | //Sanity check that we found what we're looking for 18 | if (comms == null) 19 | { 20 | Debug.Log("Cannot find voice components for team '{0}'", teamName); 21 | return; 22 | } 23 | 24 | //Add the token for the team 25 | comms.AddToken(teamName); 26 | } 27 | ``` 28 | 29 | ## Additional Global Chat Room 30 | 31 | If you want to still have a global voice chat room *and* have per team chat rooms this can be achieved by simply having the normal [global chat room](Global-Chat-Room.md) configuration with a different activation mode (e.g. a different push-to-talk input axis, such as 'v' to team chat and 'b' to global chat). 32 | 33 | ![Example of two different PTT axes](../images/VoiceBroadcastTrigger_DifferentPTT.png "Example of two different PTT axes") 34 | -------------------------------------------------------------------------------- /docs/Tutorials/Access-Control-Tokens.md: -------------------------------------------------------------------------------- 1 | !!! Video Tutorial 2 | See [this video](https://youtu.be/HXMYDbuLwVI?t=250) about access tokens. 3 | 4 | Access control tokens can be added to both [Broadcast Triggers](../Reference/Components/Voice-Broadcast-Trigger.md) and [Receipt Triggers](../Reference/Components/Voice-Receipt-Trigger.md). The trigger will not function unless the local player has *one of* the required tokens. 5 | 6 | ## Defining Required Tokens 7 | 8 | Tokens can be added and removed through the inspector: 9 | 10 | ![Receipt Trigger](../images/VoiceReceiptTrigger_Tokens.png) 11 | 12 | This receipt trigger will not function unless the local player has one of the two access tokens - 'TopSecretPassword' or 'mysocratesnote'. Tokens can also be managed with scripts: 13 | 14 | ```csharp 15 | var receiver = FindObjectOfType(); 16 | 17 | receiver.AddToken("correcthorsebatterystaple"); // Add 18 | if (receiver.ContainsToken("correcthorsebatterystaple")) // Query 19 | receiver.RemoveToken("correcthorsebatterystaple"); // Remove 20 | ``` 21 | 22 | ## Defining Available Tokens 23 | 24 | Once triggers have been configured to require tokens you will need to add some tokens to the local player. This can be done in the inspector in the same way as for triggers. Tokens added in the inspector will apply to *all* players so they can only be used as the default tokens everyone starts with. 25 | 26 | ![Receipt Trigger](../images/DissonanceComms_Tokens.png) 27 | 28 | You are more likely to want to manage tokens through scripts. When you create a player and do something which requires restricting their access to channels (e.g. joining a team) you should add the appropriate tokens to the local player: 29 | 30 | ```csharp 31 | var local = FindObjectOfType(); 32 | 33 | local.AddToken("Green Team"); 34 | ``` 35 | 36 | Assuming you have transmitters and receivers set up for every team, each one with a different token, this gives you a simple way to ensure that the player is speaking and listening to the right team channels. -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | /* Delete This Section... 2 | 3 | This template is a guideline for how to create a good issue. However it's not obligatory, feel free to skip any sections you feel are not applicable or to include any additional information you think might be helpful :) 4 | 5 | - Add [bug], [feature] or [help] to the start of the title. Depending on if this is a bug report, feature request or a call for help. 6 | - If this is a bug report make sure there is not already an open issue. If there is add a comment (following this template) to that issue instead. 7 | - If this is a help request you're welcome to open an issue, but you may get a better community response over on our [discussion forum](https://www.reddit.com/r/dissonance_voip) 8 | 9 | ...Delete This Section */ 10 | 11 | ## Context 12 | _Describe in detail the problem you are encountering, what you have tried and what happened instead_ 13 | 14 | ## Expected behaviour 15 | _Summarise exactly what you expect to happen_ 16 | 17 | ## Actual behaviour 18 | _Summarise exactly what actually happens_ 19 | 20 | ## Workaround 21 | _Not obligatory! If you have found a hack, workaround or temporary solution tell us what it is and why it is unsatisfactory as a full time fix for this issue_ 22 | 23 | ## Fix 24 | _Not obligatory! If you think you know exactly how this problem should be fixed tell us how_ 25 | 26 | ## Steps to Reproduce 27 | _Provide a detailed set of steps to reproduce the problem_ 28 | 1. 29 | 2. 30 | 3. 31 | 4. 32 | 33 | ## Your Environment 34 | _Include as many relevant details about the environment you experienced the bug in_ 35 | 36 | - **Dissonance version used**: e.g. v1.0.0 _(check Assets/Dissonance/changelog)_ 37 | 38 | - **Unity version**: e.g. 5.3.5f1 Personal _(check Help > About Unity)_ 39 | 40 | - **Editor Operating System and version**: e.g. Microsoft Windows 10 Pro 10.0.10586 (x64) _(Depends on your OS, for windows it's in the "System Information" program)_ 41 | 42 | - **Build Settings**: Tell us the build settings/platforms you have encountered this issue with e.g. Windows, x86_64, Development Build 43 | 44 | - **Link to your project**: If your project (or a bug reproduction project) is available, link it here -------------------------------------------------------------------------------- /docs/Tutorials/Channel-Volume.md: -------------------------------------------------------------------------------- 1 | The playback volume can be set by the speaker per broadcast channel. This can be used to individually reduce the volume of a speaker. For example fading off voice over a small period of time when someone stops speaking. 2 | 3 | ## Broadcast Trigger Component 4 | 5 | The broadcaster trigger component exposes 2 amplitude settings in the inspector; activation fade and trigger fade. 6 | 7 | ![Amplitude Fader Controls](../images/VoiceBroadcastTrigger-AmplitudeFaders.png) 8 | 9 | `Activation Fade` applies a fade in/out _every time_ speech is started or stopped. For example every time push-to-talk is pressed/released. This setting should be used with care; applying *any* fade-in is inadvisable as it will almost certainly cause the start of what is being said to be cut off. 10 | 11 | `Volume Trigger Fade` applies only to broadcast triggers which are using physics based volume triggers. This fade will be applied every time the player enters or exits the trigger area. 12 | 13 | Both faders have the same three controls: 14 | 15 | The `Channel Volume` slider controls the amplitude which will be reached after the fade in time has passed. This is a direct multiplier applied to the audio, values between 0 to 1 will reduce playback amplitude, values between 1 to 2 will increase playback amplitude. If both faders are in use the values will be _multiplied_ together. 16 | 17 | The `Fade In Time` slider controls how long it takes the playback amplitude to increase from zero (silent) to the `Channel Volume` slider value. 18 | 19 | The `Fade Out Time` slider controls how long it takes the playback amplitude to decrease from the `Channel Volume` slider value to zero (silent). 20 | 21 | ## Script Controlled Volume 22 | 23 | If you are [controlling channels directly](Script-Controlled-Speech.md) from your own scripts you can control volume on the channel object. 24 | 25 | ```csharp 26 | var comms = GetComponent(); 27 | 28 | //Create a channel with explicit amplitude 29 | var channel = comms.RoomsChannels.Open("Room Name", amplitudeMultiplier: 0.5f); 30 | 31 | //At any time while the channel is open change the amplitude 32 | channel.AmplitudeMultiplier = 1.0f; 33 | 34 | //Close the channel 35 | channel.Dispose(); 36 | ``` -------------------------------------------------------------------------------- /docs/Tutorials/Script-Controlled-Speech.md: -------------------------------------------------------------------------------- 1 | There are several options for controlling speech from scripts, depending on what you want to achieve. 2 | 3 | ### Muting The Local Player 4 | 5 | If you want to completely prevent a player from speaking you can set the `IsMuted` property on the `DissonanceComms` component to true. 6 | 7 | ```csharp 8 | DissonanceComms comms; 9 | comms.IsMuted = true; 10 | 11 | // User cannot speak 12 | 13 | comms.IsMuted = false; 14 | 15 | // User can speak 16 | ``` 17 | 18 | ### Deafening The Local Player 19 | 20 | If you want to completely prevent the local player from hearing any speech you can set the `IsDeafened` property on the `DissonanceComms` component to true. 21 | 22 | ```csharp 23 | DissonanceComms comms; 24 | comms.IsDeafened = true; 25 | 26 | // User cannot hear 27 | 28 | comms.IsDeafened = false; 29 | 30 | //User can hear 31 | ``` 32 | 33 | ### Muting Remote Players 34 | 35 | If you want to *locally* mute a remote player (prevent yourself from hearing them talk) you can set the `IsLocallyMuted` property on their player object. 36 | 37 | ```csharp 38 | DissonanceComms comms; 39 | var player = comms.FindPlayer(player_id); 40 | player.IsLocallyMuted = true; 41 | 42 | // You will not hear user when they speak 43 | 44 | player.IsLocallyMuted = false; 45 | 46 | // You will hear user when they speak 47 | ``` 48 | 49 | ### Disabling Triggers 50 | 51 | The [`VoiceBroadcastTrigger`](../Reference/Components/Voice-Broadcast-Trigger.md) is the normal way to trigger voice transmission. Simply disabling this component will prevent it from triggering any voice transmissions until it is enabled again. 52 | 53 | ```csharp 54 | VoiceBroadcastTrigger trigger; 55 | 56 | trigger.enabled = false; 57 | 58 | // This trigger cannot send voice 59 | 60 | trigger.enabled = true; 61 | 62 | // This trigger can send voice 63 | ``` 64 | 65 | ### Opening Channels 66 | 67 | The most general way to control player voice transmission from scripts is to open and close channels, for more information about channels see [this tutorial](Directly-Using-Channels.md). To start talking open a channel, to stop talking dispose the channel: 68 | 69 | ```csharp 70 | DissonanceComms comms; 71 | 72 | var channel = comms.RoomChannels.Open("Room ID", true, ChannelPriority.Default); 73 | 74 | //Player speech will be transmitted to the room named "Room ID" 75 | 76 | channel.Dispose(); 77 | 78 | //Player speech will no longer be transmitted by this channel 79 | ``` -------------------------------------------------------------------------------- /docs/Tutorials/Position-Tracking.md: -------------------------------------------------------------------------------- 1 | !!! Video Tutorial 2 | See [this video](https://youtu.be/HXMYDbuLwVI?t=1179) about position tracking. 3 | 4 | This tutorial will explain how to configure your project to track the position of players. This is required for 3D positional audio playback of remote player voice chat and collider trigger support for `VoiceBroadcastTrigger` and `VoiceReceiptTrigger`. 5 | 6 | ## Setup Tracking 7 | 8 | To setup position tracking you need to attach a single behaviour to all your player gameObjects. The behaviour can be found in the folder for the network integration you are using, for example for HLAPI it is located at `Assets/Dissonance/Integrations/UNet_HLAPI/HlapiPlayer.cs`. Ensure that this component is attached to *all* gameObjects in the scene which represent a player (the local player and all remote players). If you have a prefab which is used to construct your players you can simply attach the behaviour to this prefab. 9 | 10 | Some network integrations do not include player tracking scripts. In this case you will need to implement it yourself. View the documentation for custom position tracking [here](Custom-Position-Tracking.md). 11 | 12 | ![A Player Prefab with position tracking behaviour added](../images/PlayerPrefab_PositionalAudio.png) 13 | 14 | ### What Does Position Tracking Cost? 15 | 16 | Dissonance **does not send any extra data** across the network when position tracking is enabled - instead it relies on your game objects already being in the right place on every client and simply plays the audio from wherever they are in space. Enabling position tracking does not use any extra bandwidth. 17 | 18 | ## Using Position Tracking 19 | 20 | ### Positional Audio 21 | 22 | When positional audio is enabled the voice from remote players will sound like it is coming from the correct position. To enable this simply tick the "use positional data" checkbox on the voice broadcast trigger. 23 | 24 | ![A broadcast trigger with positional audio enabled](../images/VoiceBroadcastTrigger_Positional.png) 25 | 26 | ### Collider Chat Room 27 | 28 | Voice broadcaster triggers and voice receipt triggers can be configured to only send/receive audio when the local player is inside a certain volume. See [this](Collider-Chat-Room.md) tutorial for how to achieve this. 29 | 30 | ### Direct Transmit To Player 31 | 32 | When position tracking is enable transmitting to a specific player is simplified. If a `Voice Broadcast Trigger` is attached to a player entity it can be configured to transmit to the player represented by the game object. See [this](Direct-Player-Transmit.md) tutorial for details. 33 | 34 | -------------------------------------------------------------------------------- /docs/Reference/Networking/IServerClientState.md: -------------------------------------------------------------------------------- 1 | # IServerClientState 2 | 3 | Represents a single client in the server admin API. 4 | 5 | ## Properties 6 | 7 | ### Name : String 8 | 9 | The name of this client. This is the same as the `DissonanceComms.LocalPlayerName` property for this client. 10 | 11 | ### IsConnected : bool 12 | 13 | Indicates if this client is still connected to the voice session. 14 | 15 | ### Rooms: ReadOnlyCollection 16 | 17 | A collection of all the rooms this player is currently listening to. 18 | 19 | ### Channels : ReadOnlyCollection 20 | 21 | A collection of all the channels this player is currently speaking through. 22 | 23 | ### LastChannelUpdateUtc : DateTime 24 | 25 | When the `Channels` collection was last updated 26 | 27 | ### PacketLoss : float 28 | 29 | Get the estimated packet loss factor for this client (0 to 1). 30 | 31 | ## Events 32 | 33 | ### OnStartedListeningToRoom : Action 34 | 35 | Event fires when player starts listening to a room channel. 36 | 37 | ### OnStoppedListeningToRoom : Action 38 | 39 | Event fires when player stops listening to a room channel. 40 | 41 | ### StartedSpeaking : Action 42 | 43 | !!! important "" 44 | StartedSpeaking event requires `EnableChannelMonitoring = true` 45 | 46 | Event fires when player starts speaking to any channel. 47 | 48 | ### StoppedSpeaking : Action 49 | 50 | !!! important "" 51 | StoppedSpeaking event requires `EnableChannelMonitoring = true` 52 | 53 | Event fires when player stops speaking to all channels. 54 | 55 | ### OnVoicePacket : VoicePacket 56 | 57 | !!! important "" 58 | OnVoicePacket event requires `EnableChannelMonitoring = true` 59 | 60 | Event fires for every voice packet from this player. 61 | 62 | ## Methods 63 | 64 | ### RemoveFromRoom(string roomName) 65 | 66 | Immediately remove this player from a room, preventing them from listening to it. 67 | 68 | !!! note "" 69 | This does **not** prevent the client from immediately re-joining the room. 70 | 71 | ### Reset() 72 | 73 | Remove this client from the voice session, forcing them to immediately reconnect. 74 | 75 | # IServerClientState 76 | 77 | Dissonance network integrations must specify a `TPeer` type, which represents a network connection from the server to a specific client. The exact type depends on the network integration you are using. An `IServerClientState` object can be cast to an `IServerClientState` object to access additional properties. 78 | 79 | ## Properties 80 | 81 | ### Peer : ClientInfo 82 | 83 | Access the `ClientInfo` object for this client. This object exposes a `TPeer Connection { get; }` property. -------------------------------------------------------------------------------- /docs/Tutorials/Playback-Prefab.md: -------------------------------------------------------------------------------- 1 | The playback prefab is how Dissonance plays the audio signal from each player. A copy of the prefab is instantiated for each player and then moved into the correct position for positional audio to work. Creating your own playback prefab allows you to customise the AudioSource settings used for voice or attach your own script to the prefab. To use a custom prefab drag the prefab into the `Playback Prefab` field on the [Dissonance Comms](../Reference/Components/Dissonance-Comms.md) component inspector. 2 | 3 | If no prefab is set Dissonance will automatically use a default prefab. 4 | 5 | ## Prefab Components 6 | 7 | The playback prefab *must* include a `VoicePlayback` component (part of Dissonance). 8 | 9 | You may also attach a Unity `AudioSource` component, in which case you can adjust some of the settings to change how voice will be played back. However, the following settings will be overwritten by Dissonance: 10 | 11 | - Loop 12 | - Pitch 13 | - Clip 14 | - Play On Awake 15 | - Mute 16 | 17 | ## Lifetime 18 | 19 | When writing your own scripts to attach to the playback prefab it is important to remember that the lifetime is managed entirely by Dissonance. Prefab instances are recycled to reduce the amount of garbage created. This means that your custom script attached to the prefab must be able to handle being re-assigned from one player to another. 20 | 21 | When there are no instances available to use, a new one is created: 22 | 23 | 1. Prefab instantiated 24 | 1. Default components added 25 | 1. Activated 26 | 27 | When the player for an instance leaves the prefab is recycled: 28 | 29 | 1. Deactivated 30 | 1. Stored in a pool of inactive instances 31 | 32 | When another player joins an instance is retrieved and re-used: 33 | 34 | 1. Retrieved from pool 35 | 1. Activated 36 | 37 | To handle this in your script simply use the normal [Unity lifecycle events](https://docs.unity3d.com/Manual/ExecutionOrder.html): 38 | 39 | ```csharp 40 | void Awake() 41 | { 42 | // This only runs once. Use this to perform one-time setup. 43 | 44 | // e.g. Find some Dissonance components 45 | _playbackComponent = GetComponent(); 46 | _dissonanceComms = FindObjectOfType(); 47 | } 48 | 49 | void OnEnable() 50 | { 51 | // This runs every time the script is activated. Use this to perform per-player setup 52 | 53 | // e.g. find information about this player 54 | _playerState = _dissonanceComms.FindPlayer(_playbackComponent.PlayerName); 55 | } 56 | 57 | void Update() 58 | { 59 | // This will run every frame while the script is active 60 | } 61 | 62 | void OnDisable() 63 | { 64 | // This runs every time the script is deactivated. Use this to perform per-player cleanup 65 | 66 | // e.g. Remove the things which were initialised in OnEnable 67 | _playerState = null; 68 | } 69 | ``` -------------------------------------------------------------------------------- /docs/Basics/Getting-Started.md: -------------------------------------------------------------------------------- 1 | In this tutorial you will create a new project, import Dissonance and change some settings required for Dissonance to work properly. 2 | 3 | ### 1. Import Dissonance 4 | 5 | Import the Dissonance asset into the project. This will install two folders into your project: `Assets/Plugins/Dissonance` contains the main source code of Dissonance, `Assets/Dissonance` will contain any integration packages which you install. 6 | 7 | ### 2. Download Integrations 8 | 9 | When you import a new version of Dissonance a window will pop up with a list of available integrations, you can launch this window again by navigating to `Windows > Dissonance > Download Integrations`. 10 | 11 | To use Dissonance you **must** install at a network backend integration - without this Dissonance cannot send anything over the network! Refer to [these docs](Choosing-A-Network.md) for help on choosing which one to use. Each integration package includes a demo scene, you should run this demo scene once you have installed the package to verify that Dissonance is properly installed and working in your project. 12 | 13 | You may also wish to use some of our other integrations. Refer to [these docs](Other-Integrations) for a list of what's available. 14 | 15 | ### 3. Run In Background 16 | 17 | Multiplayer games need to keep running (and processing network packets) even when the game window does not have focus. To do this navigate to `Edit -> Project Settings -> Player` and enable **Run In Background**. 18 | 19 | ### 4. Per Platform Specific Setup 20 | 21 | Some platforms have special setup requirements, make sure to read the documentation for the platforms you want to work with: 22 | 23 | - [Android & Oculus Go](../Platforms/Android.md) 24 | - [iOS](../Platforms/iOS.md) 25 | - [Linux](../Platforms/Linux.md) 26 | - [MacOS](../Platforms/MacOS.md) 27 | - [Magic Leap](../Platforms/Magic Leap.md) 28 | - [Windows (Desktop)](../Platforms/Windows Desktop.md) 29 | - [Windows (UWP/Hololens)](../Platforms/Windows UWP & Hololens.md) 30 | - [Oculus OVR](../Platforms/Oculus OVR.md) 31 | 32 | ## 4. Complete! 33 | 34 | That's all you need to get a project set up and ready for Dissonance. Next, follow the appropriate Quick Start tutorial for the network system you plan to use: 35 | 36 | - [Quick Start - Mirror](Quick-Start-Mirror.md) 37 | - [Quick Start - Forge Remastered](Quick-Start-Forge-Remastered.md) 38 | - [Quick Start - Photon (PUN2)](Quick-Start-Photon.md) 39 | - [Quick Start - Photon Bolt](Quick-Start-Photon-Bolt.md) 40 | - [Quick Start - Unity Netcode For GameObjects](Quick-Start-Unity-NFGO.md) 41 | - [Quick Start - Unity Networking HLAPI](Quick-Start-UNet-HLAPI.md) 42 | - [Quick Start - Dark🗲Rift 2](Quick-Start-DR2.md) 43 | - [Quick Start - WebRTC Network](Quick-Start-PureP2P.md) 44 | - [Quick Start - Steamworks.NET](Quick-Start-Steamworks.Net-P2P.md) 45 | - [Quick Start - TNet3](Quick-Start-TNet3.md) -------------------------------------------------------------------------------- /docs/Reference/Audio/IMicrophoneCapture.md: -------------------------------------------------------------------------------- 1 | # IMicrophoneCapture 2 | 3 | This interface designates a behaviour as a microphone capture system which feeds audio into Dissonance. 4 | 5 | ## Default Microphone Capture 6 | 7 | When the DissonanceComms component `Start` method is called (just once when the component is first enabled) Dissonance will look for a sibling component which implements the `IMicrophoneCapture` interface. If it does not find a suitable component it will create a `BasicMicrophoneCapture` component which internally uses the Unity [Microphone API](https://docs.unity3d.com/ScriptReference/Microphone.html). To use your custom microphone script simply drop it onto the same gameObject as DissonanceComms. 8 | 9 | ### bool IsRecording { get; } 10 | 11 | This property indicates if the microphone component is currently recording. 12 | 13 | While this is true audio **must** be delivered to subscribers at approximately realtime rates. Delivering audio too quickly will cause buffer overflows (these are handled by Dissonance, but audio will be lost). If your capture system does not have audio available when `Update` is called it is ok to not supply audio for one or two calls (as long as a subsequent call delivers enough audio to make up for that dead time). However, if the capture system has truly stopping supply audio you must either return `true` from `Update` (to force a reset) or just return silence (to cover up for the problem). 14 | 15 | ### TimeSpan Latency { get; } 16 | 17 | This property should give the estimated latency of the microphone capture system. This is the total time from audio physically hitting the microphone hardware to the data being passed on to subscribers. 18 | 19 | ### WaveFormat StartCapture(string mic_name) 20 | 21 | Attempt to begin recording. The return value indicates what format the captured data will be. If microphone capture cannot be started for any reason this method should return null. The microphone name is passed through from the UI, how it is interpreted depends upon what kind of audio capture system you are using. 22 | 23 | Once this method has returned a non-null value `IsRecording` _must_ be set to `true` until `StopCapture` is called. 24 | 25 | ### StopCapture() 26 | 27 | Immediately stops microphone capture, discarding any data remaining in internal buffers. `IsRecording` _must_ be set to `false` after this is called. 28 | 29 | ### Subscribe(IMicrophoneSubscriber subscriber) 30 | 31 | Subscribes a new object to receive raw microphone data. 32 | 33 | ### bool Unsubscribe(IMicrophoneSubscriber subscriber) 34 | 35 | Attempts to remove a previously subscribed object. Returns whether the object was found (if it was found it is assumed it was successfully removed). 36 | 37 | ### bool Update() 38 | 39 | Pass buffered data on to the subscribers. 40 | 41 | Returns true if the microphone needs to be reset. In this case Stop will immediately be called (and start may be called afterwards). -------------------------------------------------------------------------------- /docs/Tutorials/Proximity-Chat.md: -------------------------------------------------------------------------------- 1 | # Grid Proximity 2 | 3 | Grid proximity creates an infinite grid of cells, each cell can be though of as unique chat room. Players are automatically placed into all cells which are within range of their position. This means that only nearby players can be heard. 4 | 5 | ## Setup 6 | 7 | 1. Set up [position tracking](Position-Tracking.md), this tells Dissonance where players are. 8 | 2. Add a `Voice Proximity Broadcast Trigger` to the scene. This controls when voice will be **sent to**. 9 | 10 | !!! warning "" 11 | Do **not** attach the proximity broadcast trigger to the player prefab! 12 | 13 | ![Voice Proximity Broadcast Trigger Inspector](../images/ProximityBroadcastTrigger_Inspector.png) 14 | 15 | 3. Choose a `Chat Room` for this trigger. e.g. `"Red Team Proximity Chat"` 16 | 4. Choose a range, all other players within this distance will hear your voice. 17 | 5. Choose an `Activation Mode` which decides when voice should be transmitted. 18 | 19 | 6. Add a `Voice Proximity Receipt Trigger` to the scene. This controls when voice will be **received**. 20 | 21 | !!! warning "" 22 | Do **not** attach the proximity receipt trigger to the player prefab! 23 | 24 | ![Voice Proximity Receipt Trigger Inspector](../images/ProximityReceiptTrigger_Inspector.png) 25 | 26 | 7. Set the `Chat Room` to the same value as the broadcast trigger. 27 | 8. Set the range to **exactly the same value** as the broadcast trigger. 28 | 29 | ## Distance Attenuation 30 | 31 | At the moment voices will cut off the moment they go out of range, with no fading in volume. A [Custom Playback Prefab](Playback-Prefab.html) gives you control over the [`AudioSource`](https://docs.unity3d.com/6000.1/Documentation/Manual/AudioSource-reference.html) Dissonance uses for audio playback, including the Distance/Attenuation curve. Set the curve to fade to near zero volume at the same range as the proximity broadcast trigger. 32 | 33 | ## Debugging Common Errors 34 | 35 | If proximity chat is not working, check through these quick debugging steps: 36 | 37 | - First, check that a normal (non-proximity) voice chat channel works to ensure that this is a problem with proximity chat! 38 | - Proximity chat relies on [position tracking](Position-Tracking.md) being correctly set up. While the game is running with at least 2 players connected: 39 | - Check the tracking script, attached to your player is initialised 40 | - In the `DissonanceComms` inspector expand the player list. **Every** player should have `(Positional)` next to their name. 41 | - In the `DissonanceComms` inspector expand the player list, and expand the channels list for the local player. When transmitting locally, you should see some channels appear here (with the name you set for your proximity broadcast trigger). 42 | - Select the `Proximity Broadcast Trigger`, you should see a grid of rooms (drawn as gizmos, ensure gizmos are not hidden) with the rooms near the player highlighted as you move around. -------------------------------------------------------------------------------- /docs/Reference/Components/Voice-Proximity-Broadcast-Trigger.md: -------------------------------------------------------------------------------- 1 | # Voice Proximity Broadcast Trigger 2 | 3 | The Voice Proximity Broadcast Trigger sends voice to an infinite grid of "virtual rooms", creating a proximity chat system by placing nearby players into the same rooms. 4 | 5 | ![Voice Proximity Broadcast Trigger Inspector](../../images/ProximityBroadcastTrigger_Inspector.png "Voice Proximity Broadcast Trigger Inspector") 6 | 7 | ## Room 8 | 9 | This section controls which room the trigger sends to. 10 | 11 | #### Chat Room 12 | 13 | It is possible to have several proximity broadcast systems running simultaneously (e.g. one per team), the room name uniquely identifies this room. 14 | 15 | #### Range 16 | 17 | Set the distance to transmit voice, players within this distance will be considered "near" and will be placed into the same room. 18 | 19 | !!! hint 20 | The range must be exactly the same for the broadcast trigger and the receipt trigger! 21 | 22 | ## Channel Metadata 23 | 24 | #### Priority 25 | 26 | This determines the priority which this voice has for playback. Everyone who receives audio will compare the priority of all the audio streams they are receiving and will only play out the streams with the highest priority. 27 | 28 | "None" is a special value which indicates that this broadcast trigger is setting no particular priority - the default priority for this player will be used instead. The default priority is set on the DissonanceComms component with the `PlayerPriority` property (if you do not set it it will have the priority `Default`). The priority values have this order: 29 | 30 | 1. Low 31 | 2. Default 32 | 3. Medium 33 | 4. High 34 | 35 | ## Activation Mode 36 | 37 | #### Mute 38 | 39 | When set to `true` this trigger will never activate. 40 | 41 | !!! hint 42 | This can be used to create a UI push-to-talk activated broadcast trigger - set the `Activation Mode` to `Voice Activation` and toggle the `IsMuted` property with a button. When muted by the UI no voice will be sent, when unmuted the trigger will automatically transmit when speech is detected. 43 | 44 | #### Activation Mode 45 | 46 | This controls how the broadcast trigger decides when to send voice. Activation mode can be set from scripts by modifying the `Mode` property. 47 | 48 | - `None`: Never broadcast any voice. 49 | - `Voice Activation`: Automatically broadcast when voice is detected. 50 | - `Push To Talk`: Broadcast when a given input axis is pressed. You must set the name of a Unity input axis and then configure it in the Unity input manager. 51 | - `Open`: Constantly broadcast unless muted. 52 | 53 | #### Collider Activation 54 | 55 | Only broadcast when the local player is inside a sibling collider volume. 56 | 57 | ## Access Tokens 58 | 59 | Add [Access Tokens](../../Tutorials/Access-Control-Tokens.md) which are required for this broadcaster to broadcast voice. This trigger will only broadcast if the DissonanceComms component has one or more of the necessary tokens. -------------------------------------------------------------------------------- /docs/Tutorials/Position-Tracking-For-Bolt.md: -------------------------------------------------------------------------------- 1 | !!! Video Tutorial 2 | See [this video](https://youtu.be/HXMYDbuLwVI?t=1179) about position tracking. 3 | 4 | This tutorial will explain how to configure your project to track the position of players. This is required for 3D positional audio playback of remote player voice chat and collider trigger support for `VoiceBroadcastTrigger` and `VoiceReceiptTrigger`. There are some additional steps required for this to work with Photon BOLT, if you are not using that network integration instead see the more general [position tracking tutorial](Position-Tracking.md). 5 | 6 | ## BOLT State Synchronisation 7 | 8 | First you need to modify the bolt state which you use for your player; add a new string property called `DissonancePlayerId`. 9 | 10 | ![Bolt State](../images/Bolt-State.png) 11 | 12 | Now you need to create a new script which will use this state. Dissonance includes a base class which does most of the work for you. 13 | 14 | ```csharp 15 | using Dissonance.Integrations.PhotonBolt; 16 | 17 | public class DissonancePlayerTracking 18 | : BoltPlayer< ??? > // <-- See below 19 | { 20 | public DissonancePlayerTracking() 21 | : base("DissonancePlayerId", state => state.DissonancePlayerId, (state, id) => state.DissonancePlayerId = id) 22 | { 23 | } 24 | } 25 | ``` 26 | 27 | The `???` in the example needs to be replaced with the state which bolt has generated for your player. 28 | 29 | ## Setup Tracking 30 | 31 | To setup position tracking you simply need to attach the DissonancePlayerTracking component to the game object which represents each player. 32 | 33 | Ensure that this component is attached to *all* entities in the scene which represent a player (both the local player and all remote players). If you have a prefab which is used to construct your players you can simply attach the behaviour to this prefab. 34 | 35 | ![A Player Prefab with position tracking behaviour added](../images/PlayerPrefab_PositionalAudio.png) 36 | 37 | ## Using Position Tracking 38 | 39 | ### Positional Audio 40 | 41 | When positional audio is enabled the voice from remote players will sound like it is coming from the correct position. To enable this simply tick the "use positional data" checkbox on the voice broadcast trigger. 42 | 43 | ![A broadcast trigger with positional audio enabled](../images/VoiceBroadcastTrigger_Positional.png) 44 | 45 | ### Collider Chat Room 46 | 47 | Voice broadcaster triggers and voice receipt triggers can be configured to only send/receive audio when the local player is inside a certain volume. See [this](Collider-Chat-Room.md) tutorial for how to achieve this. 48 | 49 | ### Direct Transmit To Player 50 | 51 | When position tracking is enable transmitting to a specific player is simplified. If a `Voice Broadcast Trigger` is attached to a player entity it can be configured to transmit to the player represented by the game object. See [this](Direct-Player-Transmit.md) tutorial for details. 52 | 53 | -------------------------------------------------------------------------------- /docs/Tutorials/Directly-Using-Channels.md: -------------------------------------------------------------------------------- 1 | This tutorial will explain how to use the channel API for fine grained control over when and where voice is sent. Channels are the system which are used internally by the transmit triggers which come with Dissonance. Direct use of channels requires writing scripts. 2 | 3 | Using a channel is quite simple - when a channel is open voice will be sent to whoever is appropriate. A single client may have *multiple* channels open at once, potentially all sending to the same remote player. The remote playback system will correctly handle this situation and will only play the voice back once. There are two kinds of channels, which correspond to two different types of receivers. 4 | 5 | ### Player Channels 6 | 7 | When a player channel is opened the local voice is sent to the player associated with that channel. The receiving player does not need to take any action to receive the voice. This is accessed through the ```PlayerChannels``` property on the DissonanceComms object. 8 | 9 | ```csharp 10 | DissonanceComms comms; 11 | PlayerChannel channel = comms.PlayerChannels.Open(string playerId, bool positional, ChannelPriority priority); 12 | ``` 13 | 14 | ### Room Channels 15 | 16 | When a room channel is opened no voice is sent anywhere by default. Receiving players must take an action to indicate that they wish to receive the voice (i.e. join the room). This is accessed through the ```RoomChannels``` property on the DissonanceComms object (to open a sending channel) and the ```Rooms``` property (to control receipt). 17 | 18 | ```csharp 19 | DissonanceComms comms; 20 | RoomChannel channel = comms.RoomChannels.Open(string roomId, bool positional, ChannelPriority priority); 21 | ``` 22 | 23 | ```csharp 24 | DissonanceComms comms; 25 | comms.Rooms.Join(string roomId); 26 | ``` 27 | 28 | ### Managing An Open Channel 29 | 30 | When you open a channel you receive back an object which represents that channel. This object allows you to control the channel while it is still open. 31 | 32 | ```bool IsOpen { get; }``` 33 | 34 | This property indicates if the channel is open. A channel will remain open until you explicitly close it. 35 | 36 | ```bool Positional { get; set; }``` 37 | 38 | This property indicates if this channel should be played back with positional data. You may change this value at any time. 39 | 40 | When a channel is using positional audio the remote playeback system will position the playback in space so that it sounds like the player voice is coming from the correct direction. If a channel is *not* using positional audio the voice will be non-directional. 41 | 42 | ```ChannelPriority Priority { get; set; }``` 43 | 44 | This property indicates the [priority](Channel-Priority.md) associated with data sent over this channel. You may change this value at any time. 45 | 46 | When a receiver is receiving multiple channels simultaneously it will only play the highest priority channel(s) it is currently receiving. 47 | 48 | ```Dispose()``` 49 | 50 | Close the channel. -------------------------------------------------------------------------------- /docs/Tutorials/Server-Admin-API.md: -------------------------------------------------------------------------------- 1 | ## Server Scripting 2 | 3 | Dissonance is primarily client authoritative. For example the client controls where audio is being sent to ([VoiceBroadcastTrigger](../Reference/Components/Voice-Broadcast-Trigger.md)/[Channels](Directly-Using-Channels.md)) and received from ([VoiceReceiptTrigger](../Reference/Components/Voice-Receipt-Trigger.md)/[Rooms](../Reference/Other/Rooms.md)). 4 | 5 | Dissonance has a server side API which allows server side control & monitoring of clients from the server. 6 | 7 | ### Access 8 | 9 | The server side API can be accessed from `ServerAdmin` property on the comms network component which is next to the `DissonanceComms` component in your scene. Accessing this property will return `null` on clients. 10 | 11 | ```csharp 12 | // Get the DissonanceComms object in the scene 13 | var comms = DissonanceComms.GetSingleton(); 14 | 15 | // Get the network component which is next to it. 16 | // This must be cast to the correct type for whichever network integration you are using! 17 | var network = (MirrorCommsNetwork)comms.GetComponent(); 18 | 19 | // This will return null on clients 20 | var admin = network.ServerAdmin; 21 | ``` 22 | 23 | ### Channel Monitoring 24 | 25 | Some features of the admin API require that "channel monitoring" is enabled, this makes the server partially decode packets to extract the channel data from them. By default this is **disabled** and all features which require it will return default values (null, or otherwise "empty" responses). 26 | 27 | To enable channel monitoring, set the property to `true` during initialisation: 28 | 29 | ```csharp 30 | admin.EnableChannelMonitoring = true; 31 | ``` 32 | 33 | ### Packet Spoofing 34 | 35 | !!! important "" 36 | Detecting packet spoofing requires `EnableChannelMonitoring = true` 37 | 38 | Dissonance voice packets include a header which indicates who sent the packet (i.e. who is speaking). A malicious client could change this field to send packets as if they're coming from another player. Since packets may be relayed via the server clients cannot reliably detect this. 39 | 40 | If the server ever detects this it will invoke the `VoicePacketSpoofed` event. You can subscribe to this and handle it (e.g. kick the malicious client): 41 | 42 | ```csharp 43 | admin.VoicePacketSpoofed += (IServerClientState actualSender, IServerClientState? victim) => 44 | { 45 | Debug.LogWarning($"{actualSender.Name} spoofed a packet from {(victim?.Name ?? "nobody")}."); 46 | }; 47 | ``` 48 | 49 | ### Per-Client Info 50 | 51 | Per-client information is exposed as an `IServerClientState` object for each client. See the [`IServerClientState` reference docs](../Reference/Networking/IServerClientState.md) for more information on the properties available. 52 | 53 | ```csharp 54 | // Events 55 | admin.ClientJoined += state => Debug.Log($"{state.Name} joined Dissonance session")`; 56 | admin.ClientLeft += state => Debug.Log($"{state.Name} left Dissonance session")`; 57 | 58 | // Collection 59 | foreach (var state in admin.Clients) 60 | Debug.Log(state.Name); 61 | ``` -------------------------------------------------------------------------------- /docs/Tutorials/Collider-Chat-Room.md: -------------------------------------------------------------------------------- 1 | !!! Video Tutorial 2 | See [this video](https://youtu.be/HXMYDbuLwVI?t=323) about collider chat rooms. 3 | 4 | This tutorial will introduce volume triggers for transmission and receipt triggers, and how they can be used to implement localised chat rooms which allow users standing within the same area in your game world to chat with each other. This tutorial builds upon the setup in the [Position tracking](Position-Tracking.md) guide. 5 | 6 | > [Position Tracking](Position-Tracking.md) must be set up to allow Dissonance to track player positions for collider chat rooms to function. 7 | 8 | A demo scene for this tutorial can be found in `Dissonance/Demos`. 9 | 10 | ## Step 1: Define our room volume 11 | 12 | Imagine your game has multiple physical lobby rooms all connected to a central corridor. You decide that we want players to be able to speak to and hear the other players in whatever room they are in, and for this to dynamically update as they move from room to room. 13 | 14 | The first thing you will need to do is define the volume which represents your lobby room using a Unity [trigger volume](https://unity3d.com/learn/tutorials/topics/physics/colliders-triggers). 15 | 16 | Create a new game object called "LobbyChatRoom". Add a "Box Collider" to the game object, set it's size to the size of your lobby room and check "Is Trigger". 17 | 18 | ![Box Collider](../images/BoxCollider.png) 19 | 20 | ## Step 2: Add a Receipt Trigger 21 | 22 | To allow you to hear the users talking in the lobby chat room you will need to add a "Voice Receipt Trigger" to the game object. Unlike the "Global" chat channel in the quick start guide, here you will add this to the same game object as the "Box Collider". 23 | 24 | Enable "Trigger Activation" on the "Voice Receipt Trigger" to tell the script to only listen to the room when the player is within the collider attached to the game object. 25 | 26 | ## Step 3: Define a new Chat Rooms 27 | 28 | Right now, the receipt trigger is listening to the "Global" chat room, not the chat room for the lobby. 29 | 30 | On the inspector for the "Voice Receipt Trigger" click "Config Rooms" to go to Dissonance's room configuration. By default, Dissonance creates three chat rooms; "Global", "Red Team" and "Blue Team". Click "Add Room", and rename the new room to "Lobby". 31 | 32 | ![Room Configuration with Lobby](../images/RoomConfiguration_Lobby.png) 33 | 34 | Now, go back to the receipt trigger, and change the selection in the "Chat Room" drop down to the new "Lobby" room. 35 | 36 | ![ReceiptTrigger with Lobby room available](../images/VoiceReceiptTrigger_LobbyRoom.png) 37 | 38 | > Chat rooms can be named dynamically when configuring the triggers programmatically. 39 | 40 | ## Step 4: Add a Broadcast Trigger 41 | 42 | You now have a receiver configured to hear other people talking in the lobby room, but no one is saying anything! You need to add a broadcast trigger to the room. 43 | 44 | Add a "Voice Broadcast Trigger" script to the game object. Use a Channel Type of "Room", and choose the "Lobby" room. 45 | 46 | ![BroadcastTrigger with Lobby room available](../images/VoiceBroadcastTrigger_LobbyRoom.png) 47 | 48 | ## Finished 49 | 50 | You now have a trigger box set up as a chat room. Players standing within the collider can talk to each other in the "Lobby" chat room, players who walk out of the volume will not be able to speak to or hear from the lobby room. -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-Forge-Remastered.md: -------------------------------------------------------------------------------- 1 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 2 | 3 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 4 | 5 | A demo scene for this tutorial can be found in the `Dissonance/Integrations/ForgeNetworkingRemastered/Demo` folder. Please make sure to read the include readme file before trying the demo scene. 6 | 7 | ## Step 1: Dissonance Comms Object 8 | 9 | > Dissonance runs mostly from a single game object, which should be placed somewhere near the root of your scene. This game object contains the main "Dissonance Comms" behaviour, together with the Forge networking script. 10 | 11 | To place the default Dissonance game object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/ForgeNetworkingRemastered` folder into your scene. This should create a game object with two scripts attached: "Dissonance Comms" and "Forge Remastered Comms Network". 12 | 13 | ## Step 2: Add a Broadcast Trigger 14 | 15 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 16 | 17 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to our scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 18 | 19 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 20 | 21 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 22 | 23 | To set up the broadcast trigger, change the following two settings: 24 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 25 | 2. Transmit to the 'Global' chat room. 26 | 27 | ## Step 3: Add a Receipt Trigger 28 | 29 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 30 | 31 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 32 | 33 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 34 | 35 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 36 | 37 | ## You're Done! 38 | 39 | Congratulations, you have now added voice comms to your game! What to do next? 40 | 41 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 42 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 43 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 44 | * [Send text chat messages](../Tutorials/Text-Chat.md) 45 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 46 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 47 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-Unity-NFGO.md: -------------------------------------------------------------------------------- 1 | > This Quick Start guide is for those of you integrating Dissonance into a game with **Unity Netcode For GameObjects**. 2 | 3 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 4 | 5 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 6 | 7 | A demo scene for this tutorial can be found in the `Dissonance/Integrations/UNet_NFGO/Demo` folder. 8 | 9 | ## Step 1: Dissonance Comms Object 10 | 11 | > Dissonance runs mostly from a single game object, which should be placed somewhere near the root of your scene. This object contains the main "Dissonance Comms" behaviour, together with the UNet HLAPI networking script. 12 | 13 | To place the default Dissonance object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/UNet_NFGO` folder into your scene. 14 | 15 | Once you have instantiated the `DissonanceSetup` prefab, you should have an object with two scripts attached: `DissonanceComms` and `NfgoCommsNetwork`. 16 | 17 | ## Step 2: Add a Broadcast Trigger 18 | 19 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 20 | 21 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to our scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 22 | 23 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 24 | 25 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 26 | 27 | To set up the broadcast trigger, change the following two settings: 28 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 29 | 2. Transmit to the 'Global' chat room. 30 | 31 | ## Step 3: Add a Receipt Trigger 32 | 33 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 34 | 35 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 36 | 37 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 38 | 39 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 40 | 41 | ## You're Done! 42 | 43 | Congratulations, you have now added voice comms to your game! What to do next? 44 | 45 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 46 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 47 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 48 | * [Send text chat messages](../Tutorials/Text-Chat.md) 49 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 50 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 51 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) -------------------------------------------------------------------------------- /docs/Basics/Introduction-To-Chat-Rooms.md: -------------------------------------------------------------------------------- 1 | ## Who Hears Whom? 2 | 3 | By default when a player speaks no one one will hear them - before players can communicate you need to set up where to send voice to on the speaking end and where to receive voice from on the listening end. Where to send to is controlled by a "[Voice Broadcast Trigger](../Reference/Components/Voice-Broadcast-Trigger.md)" component and where to receive from is controlled by a "[Voice Receipt Trigger](..//Reference/Components/Voice-Receipt-Trigger.md)" component. 4 | 5 | ## Speech Intent 6 | 7 | The "Voice Broadcast Trigger" does not only control who sends to where it also controls *when* voice is transmitted to the given target. This is referred to as "Activation" and is divided into two further section: does the user *want* to speak and is the user *allowed* to speak. 8 | 9 | The "Activation Mode" setting on the "Voice Broadcast Trigger" determines how the user indicates if they want to speak, this can be set to: "None", "Voice Activation" and "Push To Talk" (see the [Voice Broadcast Trigger](../Reference/Components/Voice-Broadcast-Trigger.md) reference documentation for further details). 10 | 11 | The "Trigger Activation" setting is the setting for if the user is allowed to speak, an associated trigger volume can enable and disable the broadcast as the player moves in and out of the volume. This can be used to create areas in the scene the player needs to stand inside to be heard (e.g. proximity chat). 12 | 13 | ## Sender Target 14 | 15 | ![Target setting highlighted on broadcast trigger inspector](../images/VoiceBroadcastTrigger_Targets.png "Target setting highlighted on broadcast trigger inspector") 16 | 17 | The broadcast trigger component supports three types of target: Room, Player and Self. The setting for this highlighted in the image above. 18 | 19 | #### Room 20 | 21 | When the target of a broadcaster is set to "Room" then the local voice will be sent to the given room. Other players who have subscribed to the same room will hear what is said. If a player is both sending and receiving from the same room they will *not* hear themselves speaking. 22 | 23 | #### Player 24 | 25 | When the target of a broadcaster is set to "Player" the the local voice will be sent only to the player specified by the "Recipient Player Name" field. The receiving player will automatically receive this without setting up a "Voice Receipt Trigger". 26 | 27 | #### Self 28 | 29 | When the target of a bradocaster is set to "Self" the broadcaster will look for a "Dissonance Player" component attached to the same game object and will send the local voice to the player represented by that component. This is equivalent to the player mode. The receiving player will automatically receive this without setting up a "Voice Receipt Trigger". 30 | 31 | ## Receiver 32 | 33 | ![Rooms setting on the receipt trigger inspector](../images/VoiceReceiptTrigger_Rooms.png "Rooms setting on the receipt trigger inspector") 34 | 35 | If the sending target is "Player" or "Self" then the receiving player automatically hears anything transmitted to them. However this is not the case for rooms, receiving players need to subscribe to rooms they wish to listen to, this is controlled by the "Voice Receipt Trigger". When the trigger component is activated voice will be received from the given room. 36 | 37 | ## Specific Setups 38 | 39 | This system of broadcasters and receivers is very flexible and allows for a variety of different setups. This documentation includes some specific examples but if you have a specific design in mind which is not covered here feel free to [raise an issue](https://github.com/Placeholder-Software/Dissonance/issues) or [discuss it](https://www.reddit.com/r/dissonance_voip/) with the community. -------------------------------------------------------------------------------- /docs/Tutorials/Custom-Position-Tracking.md: -------------------------------------------------------------------------------- 1 | This tutorial will explain how to write a scripts necessary to extend the Dissonance position tracking system to more advanced scenarios. The basics of position tracking are explained in [this tutorial](Position-Tracking.md). 2 | 3 | ## How Dissonance Tracks Players 4 | 5 | Dissonance tracks the position of players through a behaviour which implements the IDissonancePlayer interface. This interface exposes the necessary information for Dissonance to play back voices in the correct locations. 6 | 7 | ```csharp 8 | public interface IDissonancePlayer 9 | { 10 | string PlayerId { get; } 11 | Vector3 Position { get; } 12 | Quaternion Rotation { get; } 13 | NetworkPlayerType Type { get; } 14 | bool IsTracking { get; } 15 | } 16 | ``` 17 | 18 | Once you have implemented these five properties on your tracker you must register it with Dissonance, To do this simply call `DissonanceComms.GetSingleton().TrackPlayerPosition(this);` after tracking has started. Once this tracker is no longer in use you must unregister your tracker from Dissonance, to do this simply call `DissonanceComms.GetSingleton().StopTracking(this);`. 19 | 20 | #### PlayerId 21 | 22 | This is the ID of the player which this object represents. For the local player this is the value in the `LocalPlayerName` property on your `DissonanceComms` object. Trackers attached to remote player objects must discover the ID for the players it represents. 23 | 24 | Usually this discovery is done by sending the ID across the network, exactly how this works depends on your networking system. Most implementations follow a similar flow: 25 | 26 | 1. Discover that this instance represents the local player (e.g. `OnStartClient`, `OnStartAuthority` callback) 27 | 2. Get `DissonanceComms.GetSingleton().LocalPlayerName` and send it to the server (e.g. `ServerRPC`) 28 | 3. Server sends the `LocalPlayerName` to all instances (e.g. `SyncVar`, or `Command`) 29 | 4. Instances receive this message and then: 30 | a. set `PlayerId = ID` 31 | b. set `Type = Remote` 32 | c. set `IsTracking = true` 33 | d. call `DissonanceComms.GetSingleton().TrackPlayerPosition(this);` 34 | 35 | Care must be taken to ensure that late-joining players receive the message in step #3 correctly. For example using a `buffered RPC` or a `SyncVar`. 36 | 37 | #### Position And Rotation 38 | 39 | These properties supply the location information which is used by Dissonance to properly play positional audio. If the behaviour is attached to the object which represents the player position then implementing this is trivial: 40 | 41 | ```csharp 42 | public Vector3 Position 43 | { 44 | get { return transform.position; } 45 | } 46 | 47 | public Quaternion Rotation 48 | { 49 | get { return transform.rotation; } 50 | } 51 | ``` 52 | 53 | If you want to represent a slightly different location (e.g. your player is made of multiple objects, one of which represents the head) then you would need to change the implementation of the properties slightly: 54 | 55 | ```csharp 56 | private MonoBehaviour _head; 57 | 58 | public Vector3 Position 59 | { 60 | get { return _head.transform.position; } 61 | } 62 | 63 | public Quaternion Rotation 64 | { 65 | get { return _head.transform.rotation; } 66 | } 67 | 68 | public void OnEnable() 69 | { 70 | _head = GetHeadTransform(); 71 | } 72 | ``` 73 | 74 | #### Type 75 | 76 | This indicates to Dissonance if this object represents the (singular) local player or one of the (multiple) remote players. How you implement this property depends upon your network system. For example: 77 | 78 | ```csharp 79 | public NetworkPlayerType Type 80 | { 81 | get { return isLocalPlayer ? NetworkPlayerType.Local : NetworkPlayerType.Remote; } 82 | } 83 | ``` -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-Photon.md: -------------------------------------------------------------------------------- 1 | > This Quick Start guide is for those of you integrating Dissonance into a game with **Photon Unity Networking**. 2 | 3 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 4 | 5 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 6 | 7 | A demo scene for this tutorial can be found in the `Dissonance/Integrations/Photon/Demo` folder. 8 | 9 | ## Step 1: Dissonance Comms Object 10 | 11 | > Dissonance runs mostly from a single game object, which should be placed somewhere near the root of your scene. This object contains the main "Dissonance Comms" behaviour, together with the Photon networking script. 12 | 13 | To place the default Dissonance object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/Photon` folder into your scene. 14 | 15 | Once you have instantiated the `DissonanceSetup` prefab, you should have an object with two scripts attached: "Dissonance Comms" and `PhotonCommsNetwork`. 16 | 17 | > The Photon integration will automatically route Dissonance traffic through the Photon cloud network. 18 | 19 | ## Step 2: Add a Broadcast Trigger 20 | 21 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 22 | 23 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to our scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 24 | 25 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 26 | 27 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 28 | 29 | To set up the broadcast trigger, change the following two settings: 30 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 31 | 2. Transmit to the 'Global' chat room. 32 | 33 | ## Step 3: Add a Receipt Trigger 34 | 35 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 36 | 37 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 38 | 39 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 40 | 41 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 42 | 43 | ## You're Done! 44 | 45 | Congratulations, you have now added voice comms to your game! What to do next? 46 | 47 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 48 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 49 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 50 | * [Send text chat messages](../Tutorials/Text-Chat.md) 51 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 52 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 53 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) -------------------------------------------------------------------------------- /docs/Tutorials/Audio-Mixing.md: -------------------------------------------------------------------------------- 1 | !!! Video Tutorial 2 | See [this video](https://youtu.be/HXMYDbuLwVI?t=1516) about audio mixing. 3 | 4 | Dissonance does not have any special support built in for audio mixing, because unity already has a powerful mixing system built in which dissonance audio is routed through. You can find out more about the unity audio mixing system [here](http://blogs.unity3d.com/2014/07/24/mixing-sweet-beats-in-unity-5-0/). This tutorial offers advice about the best way to use the unity audio pipeline for VoIP. 5 | 6 | ### General Principles 7 | 8 | It can be tempting to mix voice signals in the same way as any other audio signal in your game and to add various sound effects to the voice for realism/immersion. Things such as drowning out teammates with loud gunfire, deafening players when they're hit by a flashbang or adding extreme radio fuzz when the enemy team use jammers might all sound immersive but in reality will just force people not to use the in game VoIP. Generally any audio mixing done to the voice signal should be done to improve the voice quality. 9 | 10 | ## Volume Ducking 11 | 12 | Games frequently have very loud sound effects such as explosions and gunfire which can drown out other sounds in the game. However, it would interrupt conversations if these noises also drowned out the voice signal. A naïve solution would be to increase the volume of the voice signal far above the game sounds but doing this would cause clipping and sound terrible. An alternative solution would be to reduce the volume of the game audio far below the voice signal, but doing this would cause the game sounds to lack impact even when no one is talking. The best solution is to play game sounds at full volume when no one is talking but then when someone starts talking simply "duck" the volume so the voice can be clearly heard over the game sounds. 13 | 14 | ![Example of audio mixer with ducking](../images/AudioMixing_Ducking.png "Example of audio mixer with ducking") 15 | 16 | Above is an example audio mixer for a game. Highlighted in red are all the groups of non voice data, highlighted in blue is a groups of NPC voice audio and highlighted in green is a groups of human voice data. If you do not have any groups like this then all you need to add is a single groups of "non-voice" and make sure all the game sounds play to this group. To make dissonance play to the "Human Voice" group you need to modify your playback prefab, simply drag the "Human Voice" group into the AudioSource of the prefab and all voice will play to that group. 17 | 18 | The yellow arrows indicate "sends", a send sends audio from one signal processor to another. At the receiving end of the sends is a "Duck Volume" effect, this reduces the volume of the group relative to the volume of the signal it receives via a send. The setup shown above has *two* volume ducks and *three* sends. The human voice sends to "Non-Voice" and "NPC Voice", this means than when a human speaks both NPC voices and other sounds get quieter. The "NPC Voice" has a single send to the "Non-Voice" group, this means that when an NPC speaks other sounds get quieter. 19 | 20 | ## Sound Effects 21 | 22 | As mentioned above you should be very cautious about applying any sound effects to the voice signal which are not for the purpose of enhancing the voice quality. However there are some situations where applying sound effects to voices could sound good, for example keeping allied communications clean, but adding a subtle radio distortion effect to enemy communications. Applying an effect is very simple, simply click add on the audio group and select the effect you want. 23 | 24 | ![Example of audio mixer with distortion](../images/AudioMixing_Distortion.png "Example of audio mixer with distortion") 25 | 26 | Above is an example of an audio group with a [distortion](https://docs.unity3d.com/Manual/class-AudioDistortionEffect.html) effect applied. -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-PureP2P.md: -------------------------------------------------------------------------------- 1 | > This Quick Start guide is for those of you integrating Dissonance into a game with the **WebRTC Network** asset. 2 | 3 | > **This integration requires Dissonance 6.2.5 or greater.** 4 | 5 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 6 | 7 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 8 | 9 | A demo scene for this tutorial can be found in the `Assets/Dissonance/Integrations/PureP2P/Demo` folder. 10 | 11 | ## Step 1: Dissonance Comms Object 12 | 13 | > Dissonance runs mostly from a single game object, which should be placed somewhere near the root of your scene. This object contains the main "Dissonance Comms" behaviour, together with the PureP2P networking script. 14 | 15 | To place the default Dissonance object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/PureP2P` folder into your scene. 16 | 17 | Once you have instantiated the `DissonanceSetup` prefab, you should have an object with two scripts attached: `Dissonance Comms` and `Pure P2P Comms Network`. 18 | 19 | ### Step 1a: Setup Network Session 20 | 21 | Dissonance internally manages the WebRTC network session, automatically hosting a session and connecting to other peers as they join. From your script you simply need to call `InitializeAsServer` or `InitializeAsClient` on the `PureP2PCommsNetwork` component and supply the same session ID to both calls. If the peer leaves the session you will need to start a new server with a new session ID and connect all the clients again. 22 | 23 | ## Step 2: Add a Broadcast Trigger 24 | 25 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 26 | 27 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to our scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 28 | 29 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 30 | 31 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 32 | 33 | To set up the broadcast trigger, change the following two settings: 34 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 35 | 2. Transmit to the 'Global' chat room. 36 | 37 | ## Step 3: Add a Receipt Trigger 38 | 39 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 40 | 41 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 42 | 43 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 44 | 45 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 46 | 47 | ## You're Done! 48 | 49 | Congratulations, you have now added voice comms to your game! What to do next? 50 | 51 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 52 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 53 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 54 | * [Send text chat messages](../Tutorials/Text-Chat.md) 55 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 56 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 57 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-Fusion.md: -------------------------------------------------------------------------------- 1 | > This Quick Start guide is for those of you integrating Dissonance into a game with **Photon Fusion**. 2 | 3 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 4 | 5 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 6 | 7 | A demo scene for this tutorial can be found in the `Dissonance/Integrations/PhotonFusion/Demo` folder. 8 | 9 | ## Fusion Multi Peer 10 | 11 | !!! warning "Photon Fusion Multi Peer" 12 | Dissonance does not support [Fusion Multi Peer Mode](https://doc.photonengine.com/fusion/current/manual/multipeer). 13 | 14 | Photon Fusion supports [multi peer mode](https://doc.photonengine.com/fusion/current/manual/multipeer) which allows multiple clients to run in one Unity editor instance, this is great for rapid testing. However, Dissonance uses some resources that fundamentally cannot be shared (e.g. the microphone) and does not support this mode. 15 | 16 | ## Step 1: Dissonance Comms Object 17 | 18 | > Dissonance runs mostly from a single game object, which should be created as a child of your Photon Fusion "Network Runner". This object contains the main "Dissonance Comms" behaviour, together with the Photon Fusion networking script. 19 | 20 | To place the default Dissonance object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/PhotonFusion` folder into your "Network Runner" GameObject. 21 | 22 | Once you have instantiated the `DissonanceSetup` prefab, you should have an object with two scripts attached: `DissonanceComms` and `FusionCommsNetwork`. 23 | 24 | ## Step 2: Add a Broadcast Trigger 25 | 26 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 27 | 28 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to our scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 29 | 30 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 31 | 32 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 33 | 34 | To set up the broadcast trigger, change the following two settings: 35 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 36 | 2. Transmit to the 'Global' chat room. 37 | 38 | ## Step 3: Add a Receipt Trigger 39 | 40 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 41 | 42 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 43 | 44 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 45 | 46 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 47 | 48 | ## You're Done! 49 | 50 | Congratulations, you have now added voice comms to your game! What to do next? 51 | 52 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 53 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 54 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 55 | * [Send text chat messages](../Tutorials/Text-Chat.md) 56 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 57 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 58 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-Mirror.md: -------------------------------------------------------------------------------- 1 | > This Quick Start guide is for those of you integrating Dissonance into a game with the **Mirror Networking**. You must use a network backend which supports unreliable networking such as **Ignorance**. 2 | 3 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 4 | 5 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 6 | 7 | A demo scene for this tutorial can be found in the `Dissonance/Integrations/MirrorIgnorance/Demo` folder. 8 | 9 | ## Step 1: Dissonance Comms Object 10 | 11 | > Dissonance runs mostly from a single game object, which should be placed somewhere near the root of your scene. This object contains the main "Dissonance Comms" behaviour, together with the Mirror networking script. 12 | 13 | To place the default Dissonance object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/MirrorIgnorance` folder into your scene. 14 | 15 | Once you have instantiated the `DissonanceSetup` prefab, you should have an object with two scripts attached: "Dissonance Comms" and `MirrorIgnoranceCommsNetwork`. 16 | 17 | ### Step 1a: Setup Network Manager 18 | 19 | In this configuration Dissonance sends it's network packets through Mirror - this means you need a Mirror session setup for Dissonance to use. 20 | 21 | To create a high level network session add a `Network Manager` to your scene, this is a Mirror component which will handle setting up your network. If you need a basic UI for test purposes also add a `Network Manager HUD` to your scene, this is another Mirror component which shows a simple UI for creating and joining sessions. 22 | 23 | ## Step 2: Add a Broadcast Trigger 24 | 25 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 26 | 27 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to our scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 28 | 29 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 30 | 31 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 32 | 33 | To set up the broadcast trigger, change the following two settings: 34 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 35 | 2. Transmit to the 'Global' chat room. 36 | 37 | ## Step 3: Add a Receipt Trigger 38 | 39 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 40 | 41 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 42 | 43 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 44 | 45 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 46 | 47 | ## You're Done! 48 | 49 | Congratulations, you have now added voice comms to your game! What to do next? 50 | 51 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 52 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 53 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 54 | * [Send text chat messages](../Tutorials/Text-Chat.md) 55 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 56 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 57 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-Photon-Bolt.md: -------------------------------------------------------------------------------- 1 | > This Quick Start guide is for those of you integrating Dissonance into a game with the **[Photon BOLT networking asset](https://www.assetstore.unity3d.com/en/#!/content/83233)** 2 | 3 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 4 | 5 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 6 | 7 | A demo scene for this tutorial can be found in the `Dissonance/Integrations/PhotonBolt/Demo` folder. 8 | 9 | ## Setup BOLT 10 | 11 | Photon BOLT requires defining the packet types it can send and receive in the Unity editor. Add two new Events (both with no properties): 12 | 13 | * DissonanceToClient 14 | * DissonanceToServer 15 | 16 | For the Demo scene to correctly synchronise player positions you will also need to add a new "State", details of this are in the README in the demo folder. 17 | 18 | ## Step 1: Dissonance Comms Object 19 | 20 | > Dissonance runs mostly from a single game object, which should be placed somewhere near the root of your scene. This object contains the main "Dissonance Comms" behaviour, together with the Photon networking script. 21 | 22 | To place the default Dissonance object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/PhotonBolt` folder into your scene. 23 | 24 | Once you have instantiated the `DissonanceSetup` prefab, you should have an object with two scripts attached: "Dissonance Comms" and `Bolt Comms Network`. 25 | 26 | > The Photon BOLT integration will automatically route Dissonance traffic through an established BOLT session. 27 | 28 | ## Step 2: Add a Broadcast Trigger 29 | 30 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 31 | 32 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to our scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 33 | 34 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 35 | 36 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 37 | 38 | To set up the broadcast trigger, change the following two settings: 39 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 40 | 2. Transmit to the 'Global' chat room. 41 | 42 | ## Step 3: Add a Receipt Trigger 43 | 44 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 45 | 46 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 47 | 48 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 49 | 50 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 51 | 52 | ## You're Done! 53 | 54 | Congratulations, you have now added voice comms to your game! What to do next? 55 | 56 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 57 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 58 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 59 | * [Send text chat messages](../Tutorials/Text-Chat.md) 60 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 61 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 62 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) 63 | 64 | Note that setting up positional audio for bolt requires some extra steps, see this article for more detail: 65 | 66 | * [3D Positional Audio For BOLT](/Tutorials/Position-Tracking-For-Bolt) -------------------------------------------------------------------------------- /docs/Reference/Audio/VoiceSettings.md: -------------------------------------------------------------------------------- 1 | # Voice Settings 2 | 3 | Voice settings is a central place to control various audio settings Dissonance uses. Voice settings can be accessed through `Window > Dissonance > Quality Settings`. 4 | 5 | ![Voice Settings Editor](../../images/VoiceSettings_Editor.png) 6 | 7 | ## Persistence 8 | 9 | These settings are serialized into an asset file at `Assets/Plugins/Dissonance/Resources/VoiceSettings.asset` and are also saved into [PlayerPrefs](https://docs.unity3d.com/ScriptReference/PlayerPrefs.html). `PlayerPrefs` override the values saved in the asset. 10 | 11 | Because the settings are saved into an asset the values you choose will be built into your game and will be the default values used by all players. 12 | 13 | Because settings are saved into `PlayerPrefs` you can expose the settings to end users in your UI and the values will be saved on a per user basis. 14 | 15 | ## Frame Size 16 | 17 | - Tiny (10ms) **LAN ONLY** 18 | - Small (20ms) 19 | - Medium (40ms) 20 | - Large (60ms) 21 | 22 | This setting determines how much voice data is sent in a single network packet. There is some overhead associated with each individual packet - using larger values will send less packets-per-second and thus reduce CPU load and network usage. However, larger packets introduce more latency (more delay between speaking and hearing). Latency is a very important aspect of perceived voice quality and lowering this will improve the flow of conversations. 23 | 24 | The `Tiny` option (10ms packets) is the lowest latency option. However due to the very high rate of packets (100/second) it is **not suitable for use over the internet**, only use it in a local area network when latency is very important (e.g. shared space VR). 25 | 26 | ## Audio Quality 27 | 28 | - Low (~10KB/s) 29 | - Medium (~17KB/s) 30 | - High (~24KB/s) 31 | 32 | This setting determines the bitrate the encoder will target - higher values result in higher audio quality but slightly more CPU load and network usage. 33 | 34 | ## Forward Error Correction 35 | 36 | Forward error correction includes extra information in audio packets when network conditions are bad. When a packet is lost due to bad network conditions the audio decoder can use this extra information in other packets to reconstruct a lower quality version of the lost audio. This can almost completely conceal small amounts of packet loss at the cost of ~10% more data used when bad network conditions are detected. 37 | 38 | ## Noise Suppression 39 | 40 | This setting determines how much noise suppression will be applied to the microphone signal before transmission. Noise in this sense is any sound which is not speech such as computer fans or microphone hiss. Noise suppression will not remove echoes other other voices playing through your speakers. 41 | 42 | Noise suppression is not perfect and may sometimes distort speech, higher levels will remove more background noise but also risk more distortion of speech. However, the risk is fairly low - the distortion is quite minor and the noise suppressor is adaptive so it will only apply really high noise suppression when there is a lot of background noise. 43 | 44 | ## Voice Detector Sensitivity 45 | 46 | This setting determines how sensitive the voice detector is. This settings is a tradeoff between accuracy (never classifying non-voice audio as voice) and sensitivity (never classifying voice audio as non-voice). Higher values will send more non-voice background noise. 47 | 48 | ## Acoustic Echo Cancellation 49 | 50 | These settings control the acoustic echo canceller, this observes sounds coming out of the speakers and then attempts to remove these sounds from the microphone signal after a short delay. It automatically calibrates the delay so expect a short period (10-40 seconds) where no echoes will be cancelled, if there is no sounds coming out of the speakers at all (or the microphone is not detecting those sounds) it will not be able to calibrate the delay. Refer to [these docs](../../Tutorials/Acoustic-Echo-Cancellation.md) for a tutorial on correctly setting up the acoustic echo canceller. 51 | 52 | #### Mobile Echo Cancellation 53 | 54 | This controls how much the echo canceller tries to cancel echo on mobile devices. 55 | 56 | #### Desktop Echo Cancellation 57 | 58 | This controls how much the echo canceller tries to cancel echo on desktop PCs. 59 | 60 | ## Audio Duck Attenuation 61 | 62 | This controls how much remote voices will be attenuated by (reduced in volume) when the local speaker is transmitting. -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-DR2.md: -------------------------------------------------------------------------------- 1 | > This Quick Start guide is for those of you integrating Dissonance into a game with **Dark Rift 2**. 2 | 3 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 4 | 5 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 6 | 7 | A demo scene for this tutorial can be found in the `Dissonance/Integrations/DarkRift2/Demo` folder. Note that to use the demo scene you must install the server plugins (see section 1a). 8 | 9 | ## Step 1: Dissonance Comms Object 10 | 11 | > Dissonance runs mostly from a single game object, which should be placed somewhere near the root of your scene. This game object contains the main "Dissonance Comms" behaviour, together with the Dark Rift networking script. 12 | 13 | To place the default Dissonance game object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/DarkRift2` folder into your scene. This should create a game object with two scripts attached: "Dissonance Comms" and "Dark Rift 2 Comms Network". 14 | 15 | ## Step 1a: Server Setup 16 | 17 | Dark Rift has a system of server side plugins to process packets, Dissonance includes two plugins. For the demo scene there is a `DissonanceDemoPlugin.dll`, this is a very basic plugin to synchronise the positions of characters in the demo scene. There is also the `DissonanceServerPlugin.dll` which runs the Dissonance server logic. The precompiled plugin DLL files are included in the package, simply drop them into the plugins folder on your dark rift server. Sometimes these plugins can confuse Unity because they are not Unity plugins but Unity might try to load them anyway - if you have an error which mentions `... ambiguous between the following methods or properties` then you should remove the server plugins from with the Unity project to prevent Unity from trying to load them. 18 | 19 | If you need to modify the code of the plugins contact `admin@placeholder-software.co.uk` with your invoice number to request the source code. 20 | 21 | ## Step 2: Add a Broadcast Trigger 22 | 23 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 24 | 25 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to your scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 26 | 27 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 28 | 29 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 30 | 31 | To set up the broadcast trigger, change the following two settings: 32 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 33 | 2. Transmit to the 'Global' chat room. 34 | 35 | ## Step 3: Add a Receipt Trigger 36 | 37 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 38 | 39 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 40 | 41 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 42 | 43 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 44 | 45 | ## You're Done! 46 | 47 | Congratulations, you have now added voice comms to your game! What to do next? 48 | 49 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 50 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 51 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 52 | * [Send text chat messages](../Tutorials/Text-Chat.md) 53 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 54 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 55 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-UNet-HLAPI.md: -------------------------------------------------------------------------------- 1 | > This Quick Start guide is for those of you integrating Dissonance into a game with the **Unity Networking High Level API**. 2 | 3 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 4 | 5 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 6 | 7 | A demo scene for this tutorial can be found in the `Dissonance/Integrations/UNet_HLAPI/Demo` folder. 8 | 9 | ## Step 1: Dissonance Comms Object 10 | 11 | > Dissonance runs mostly from a single game object, which should be placed somewhere near the root of your scene. This object contains the main "Dissonance Comms" behaviour, together with the UNet HLAPI networking script. 12 | 13 | To place the default Dissonance object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/UNet_HLAPI` folder into your scene. 14 | 15 | Once you have instantiated the `DissonanceSetup` prefab, you should have an object with two scripts attached: "Dissonance Comms" and `HlapiCommsNetwork`. 16 | 17 | ### Step 1a: Setup Network Manager 18 | 19 | In this configuration Dissonance sends it's network packets through the UNet High Level API - this means you need a high level network session setup for Dissonance to use. 20 | 21 | To create a high level network session add a `Network Manager` to your scene, this is a Unity component which will handle setting up your network. If you need a basic UI for test purposes also add a `Network Manager HUD` to your scene, this is another Unity component which shows a simple UI for creating and joining sessions. 22 | 23 | Dissonance needs two network channels to send it's data through. On the `Network Manager` component check the `Advanced Configuration` checkbox and add two new channels, configure one as `Reliable Sequenced` and the other as `Unreliable`. In the Dissonance `Hlapi Comms Network` inspector check the `Reliable Channel` and `Unreliable Channel` fields correspond to the channels numbers in the `Network Manager`. 24 | 25 | ![HLAPI QoS Channels](../images/HLAPI_QoS_Channels.png) 26 | 27 | ## Step 2: Add a Broadcast Trigger 28 | 29 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 30 | 31 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to our scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 32 | 33 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 34 | 35 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 36 | 37 | To set up the broadcast trigger, change the following two settings: 38 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 39 | 2. Transmit to the 'Global' chat room. 40 | 41 | ## Step 3: Add a Receipt Trigger 42 | 43 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 44 | 45 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 46 | 47 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 48 | 49 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 50 | 51 | ## You're Done! 52 | 53 | Congratulations, you have now added voice comms to your game! What to do next? 54 | 55 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 56 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 57 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 58 | * [Send text chat messages](../Tutorials/Text-Chat.md) 59 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 60 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 61 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-Steamworks.Net-P2P.md: -------------------------------------------------------------------------------- 1 | > This Quick Start guide is for those of you integrating Dissonance into a game with the **Steamworks.NET P2P API** 2 | 3 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 4 | 5 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 6 | 7 | A demo scene for this tutorial can be found in the `Dissonance/Integrations/SteamworksP2P/Demo` folder. 8 | 9 | ## Step 1: Dissonance Comms Object 10 | 11 | > Dissonance runs mostly from a single game object, which should be placed somewhere near the root of your scene. This object contains the main "Dissonance Comms" behaviour, together with the Steamworks P2P networking script. 12 | 13 | To place the default Dissonance object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/SteamworksP2P` folder into your scene. 14 | 15 | Once you have instantiated the `DissonanceSetup` prefab, you should have an object with two scripts attached: "Dissonance Comms" and `SteamworksP2PCommsNetwork`. 16 | 17 | ### Step 1a: Setup Network Session 18 | 19 | Dissonance does not manage your steamworks session, instead it uses whatever session you have already setup. This gives you maximum control over how you want the network session to be configured. Refer to the [Steamworks Networking Documentation](https://partner.steamgames.com/doc/features/multiplayer/networking) for details on how to setup a session. You can see example code in the `SteamworksDemoUi` component in the `Assets/Dissonance/Integrations/SteamworksP2P/Demo` folder. 20 | 21 | Once you have a Steamworks session running you need to inform Dissonance about the state of the session when it changes. When you have a session running you need to start Dissonance, call one of `InitializeAsDedicatedServer`, `InitializeAsServer` or `InitializeAsClient` on the `SteamworksP2PCommsNetwork` component. The server is the central control point of the session, if it leaves the game you must stop Dissonance and pick a new server. When a player joins the session you must call the `PeerConnected` method. When a player leaves the session you must call the `PeerDisconnected` method. 22 | 23 | ## Step 2: Add a Broadcast Trigger 24 | 25 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 26 | 27 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to our scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 28 | 29 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 30 | 31 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 32 | 33 | To set up the broadcast trigger, change the following two settings: 34 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 35 | 2. Transmit to the 'Global' chat room. 36 | 37 | ## Step 3: Add a Receipt Trigger 38 | 39 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 40 | 41 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 42 | 43 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 44 | 45 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 46 | 47 | ## You're Done! 48 | 49 | Congratulations, you have now added voice comms to your game! What to do next? 50 | 51 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 52 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 53 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 54 | * [Send text chat messages](../Tutorials/Text-Chat.md) 55 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 56 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 57 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) -------------------------------------------------------------------------------- /docs/Tutorials/Custom-Microphone-Capture.md: -------------------------------------------------------------------------------- 1 | By default Dissonance uses the `BasicMicrophoneCapture` behaviour to record audio from a microphone using the Unity [Microphone API](https://docs.unity3d.com/ScriptReference/Microphone.html) and feed it into Dissonance. However this script is not ideal for all use cases. You can replace the microphone capture system in Dissonance by creating a new behaviour which implements `IMicrophoneCapture` and adding the script to the same gameObject as the `DissonanceComms` behaviour. 2 | 3 | This tutorial will explain how to build a replacement capture system which streams audio from a file. before following the tutorial make sure you've read the [reference docs](../Reference/Audio/IMicrophoneCapture.md) so you understand what the `IMicrophoneCapture` interface means. 4 | 5 | ## Step 1 : Basic Setup 6 | 7 | First you need to create a new script with the IMicrophoneCapture interface on it and drop it onto the same GameObject as the DissonanceComms component. 8 | 9 | [Here is an example script](https://gist.github.com/martindevans/266553f7405c393e5a41d4729b67fa1e). If you run the scene with this you should see a single exception printed to the console coming from the `StartCapture` method. 10 | 11 | ## Step 2 : Start And Stop 12 | 13 | Now you need to properly start and stop the script without throwing exceptions. 14 | 15 | `StartCapture` should return the format of the audio you will be providing. This **must** be mono (i.e. 1 channel) and any sample rate is acceptable (just use whatever is most convenient for you). If your capture system is not ready you can return null to prevent start-up. If you return a non-null value you **must** set `IsRecording` to `true` and you **should** set `Latency` to an appropriate value. The `Latency` value indicates an estimate of the time between sound physically hitting the microphone to submitting the audio to Dissonance, if you don't know this value leave it set to zero. 16 | 17 | `StopCapture` should do whatever you need to stop the underlying capture system. Once this is done you **must** set `IsRecording` to `false`. 18 | 19 | `Subscribe` and `Unsubscribe` should simply keep a list of subscribers. You can implement this as a `List` where `Subscribe` just calls `Add` and `Unsubscribe` just calls `Remove` and returns the value. 20 | 21 | [here is an example script](https://gist.github.com/martindevans/47127ccde8e5b7abeaa4cc0b49d60759). If you run the scene with this you should see exceptions printed to the console every frame coming from the `UpdateSubscribers` method. 22 | 23 | ## Step 3 : Streaming Silence 24 | 25 | Now you need to stream some audio to Dissonance to stop the script throwing exceptions every frame. 26 | 27 | When `IsRecording` is `true` (i.e. after `StartCapture` has been called and before `StopCapture` has been called) your capture script **must** provide audio at approximately a realtime rate. Dissonance will try to handle slight "bumps" (e.g. audio arriving slightly early or late) but overall you must supply audio at the correct rate. For example the `BasicMicrophoneCapture` script assumes that the microphone supplies audio at the correct rate, if you're reading from some kind of recording hardware this is probably a good assumption to make. The basic process for the microphone capture (which you may be able to replicate in your custom system) is: 28 | 29 | 1. Drain all data from the recording hardware into a buffer 30 | 2. Copy as much data out of the buffer into a preallocated array as possible 31 | 3. Submit preallocated array to subscribers 32 | 4. if there is data left in the buffer, goto 2 33 | 34 | For this step we won't interact with any hardware, instead we'll just submit _silence_ to Dissonance at the correct rate. 35 | 36 | [here is an example script](https://gist.github.com/martindevans/2ab034c885cf0c038db8fda471336596) which implements UpdateSubscribers by simply submitting _silence_ at the correct rate. If you run this everything should work as expected in Dissonance (no exceptions), but of course you will not hear anything. This works by preallocating an array of 960 `float`, which represents 20ms of audio at 48kHz sample rate. Every time 20ms have elapsed, the buffer is submitted to Dissonance. Note that time is measured using `unscaledDeltaTime`, since audio needs to run at _real_ time rate. 37 | 38 | ## Step 4 : File Streaming 39 | 40 | Finally we'll add a basic file streaming system, this will read an audio file and play it into Dissonance. For simplicity this will _not_ handle decoding of the audio from any well know format, instead you should transcode the audio into raw samples. You can do this with [ffmpeg](https://ffmpeg.org/): 41 | 42 | > ffmpeg.exe -re -i AudioFile.wav -f f32le -ar 48000 -ac 1 output.raw 43 | 44 | [here is an example script](https://gist.github.com/martindevans/ad4df4d1f771538bb7f474756cbb3711) which implements this. The basic process is the same as the silence system: 45 | 46 | 1. Count time passed using `unscaledDeltaTime` 47 | 2. When 20ms have passed, read up to 20ms of audio from the file (as bytes) 48 | 3. Copy bytes into float buffer 49 | 4. Submit to all subscribers -------------------------------------------------------------------------------- /docs/Basics/Quick-Start-TNet3.md: -------------------------------------------------------------------------------- 1 | > This Quick Start guide is for those of you integrating Dissonance into a game with the **[TNet3](https://assetstore.unity.com/packages/tools/network/networking-and-serialization-tools-tnet-3-56798?aid=1100lJDF)** asset. 2 | 3 | > **This integration requires Dissonance 6.4.2 or greater.** 4 | 5 | This tutorial will guide you through the steps required to get a basic Dissonance setup working in your project. By the end of this tutorial, you will having working voice comms with all users talking in a global chat room. 6 | 7 | Before beginning this tutorial, please refer to the [installation guide](Getting-Started.md) to learn how to install Dissonance into your project. 8 | 9 | A demo scene for this tutorial can be found in the `Assets/Dissonance/Integrations/TNet3/Demo` folder. 10 | 11 | ## Step 1: Dissonance Comms Object 12 | 13 | > Dissonance runs mostly from a single game object, which should be placed somewhere near the root of your scene. This object contains the main "Dissonance Comms" behaviour, together with the TNet3 networking script. 14 | 15 | To place the default Dissonance object into your scene, drag and drop the `DissonanceSetup` prefab from the `Dissonance/Integrations/TNet3` folder into your scene. 16 | 17 | Once you have instantiated the `DissonanceSetup` prefab, you should have an object with two scripts attached: `Dissonance Comms` and `Tnet3 Comms Network`. 18 | 19 | ### Step 1a: Network Channel Setup 20 | 21 | A single TNet3 server hosts multiple channels at once, players can only send and receive packets to channels they have joined. The Dissonance integration automatically hosts a voice session in a separate channel - this means you can potentially host multiple completely independent voice chat sessions on a single TNet3 server. Once your game is started you need to choose which voice session to host/join for each peer that connects: 22 | 23 | To begin hosting a new session in a channel: 24 | 25 | ```csharp 26 | var tcnc = FindObjectOfType(); 27 | 28 | tncn.HostVoiceChannel(channel_id, max_players, "password", is_dedicated_server); 29 | ``` 30 | 31 | This will begin hosting a new Dissonance voice chat session in the channel identified by `channel_id`. If `is_dedicated_server` is true then the local instance will _not_ be able to send or receive audio - it is simpl acting as a network host. 32 | 33 | To join an existing session: 34 | 35 | ```csharp 36 | var tcnc = FindObjectOfType(); 37 | 38 | tcnc.JoinVoiceChannel(channel_id, "password"); 39 | ``` 40 | 41 | This will attempt to join a session in the specified `channel_id`. 42 | 43 | These methods can be called again at any time to change the mode of Dissonance. 44 | 45 | ## Step 2: Add a Broadcast Trigger 46 | 47 | You now have a functional Dissonance comms system, but you are not yet transmitting anything. 48 | 49 | Before you can speak to anyone, you need to add a "Voice Broadcast Trigger" script to the scene. This script can be placed anywhere, but for this tutorial, you should simply add it to the DissonanceSetup game object you created in step 1. 50 | 51 | The "Voice Broadcast Trigger" controls when the user's microphone is being transmitted to other players, and to whom the user is talking. There are many configuration options on this script to provide more advanced control of under what situations we should be transmitting and who to, but for this tutorial simply leave the settings at default. 52 | 53 | ![Broadcast Trigger Configuration](../images/VoiceBroadcastTrigger_Default.png) 54 | 55 | To set up the broadcast trigger, change the following two settings: 56 | 1. Transmit on *Voice Activation*. This means Dissonance will transmit whenever it detects that the user is speaking. 57 | 2. Transmit to the 'Global' chat room. 58 | 59 | ## Step 3: Add a Receipt Trigger 60 | 61 | Now you are talking into the 'Global' room automatically whenever you speak. However, you still can't hear anyone speaking. This is because you are not listening to the 'Global' room and so you are not receiving any of these transmissions. 62 | 63 | To listen to the 'Global' room, add a "Voice Receipt Trigger" to the scene. Like the "Voice Broadcast Trigger", this script can be placed anywhere, but for this tutorial you should simply add it to the DissonanceSetup game object. 64 | 65 | ![Receipt Trigger Configuration](../images/VoiceReceiptTrigger_Default.png) 66 | 67 | Again, leave this on the default configuration, which should have trigger activation disabled and be listening to the 'Global' chat room. 68 | 69 | ## You're Done! 70 | 71 | Congratulations, you have now added voice comms to your game! What to do next? 72 | 73 | * [Transmit on key press with Push-to-Talk](../Tutorials/Push-to-Talk.md) 74 | * [Set up per-team chat channels](../Tutorials/Team-Chat-Rooms.md) 75 | * [Direct message another player](../Tutorials/Direct-Player-Transmit.md) 76 | * [Send text chat messages](../Tutorials/Text-Chat.md) 77 | * [3D Positional Audio](../Tutorials/Position-Tracking.md) 78 | * [3D Area Chat Rooms](../Tutorials/Collider-Chat-Room.md) 79 | * [Proximity Chat: Talk to players near each other](../Tutorials/Proximity-Chat.md) -------------------------------------------------------------------------------- /docs/Reference/Other/VoicePlayerState.md: -------------------------------------------------------------------------------- 1 | # VoicePlayerState 2 | 3 | This object exposes properties to do with other players in a Dissonance session. There is one of these objects per player (including the local player) in the `Players` property on the DissonanceComms component. You can also get one of these objects for a specific player with the `FindPlayer` method on the DissonanceComms component. 4 | 5 | ```csharp 6 | //Get your comms component 7 | DissonanceComms comms; 8 | 9 | //Get a specific player 10 | VoicePlayerState player = comms.FindPlayer("Player ID"); 11 | 12 | //Enumerate all players in the session 13 | for (var i = 0; i < comms.Players.Count; i++) { 14 | VoicePlayerState player = comms.Players[i]; 15 | } 16 | ``` 17 | 18 | 19 | ## Events 20 | 21 | ### OnStartedSpeaking : Action<VoicePlayerState> 22 | 23 | This event is raised every time this player starts speaking. It is passed the state object for this player. 24 | 25 | ```csharp 26 | VoicePlayerState.OnStartedSpeaking += player => { 27 | Debug.Log("Player " + player.Name + " Started Speaking"); 28 | } 29 | ``` 30 | 31 | ### OnStoppedSpeaking : Action<VoicePlayerState> 32 | 33 | This event is raised every time this player stops speaking. It is passed the state object for this player. 34 | 35 | ```csharp 36 | VoicePlayerState.OnStoppedSpeaking += player => { 37 | Debug.Log("Player " + player.Name + " Stopped Speaking"); 38 | } 39 | ``` 40 | 41 | ### OnEnteredRoom : Action<VoicePlayerState, string> 42 | 43 | This event is raised every time this player begins listening to a new room. It is passed the state object for this player and the name of the room. 44 | 45 | ```csharp 46 | VoicePlayerState.OnEnteredRoom += (player, room) => { 47 | Debug.Log("Player " + player.Name + " began listening to room " + room); 48 | } 49 | ``` 50 | 51 | ### OnExitedRoom : Action<VoicePlayerState, string> 52 | 53 | This event is raised every time this player stops listening to a room. It is passed the state object for this player and the name of the room. 54 | 55 | ```csharp 56 | VoicePlayerState.OnExitedRoom += (player, room) => { 57 | Debug.Log("Player " + player.Name + " stopped listening to room " + room); 58 | } 59 | ``` 60 | 61 | ### OnLeftSession : Action<VoicePlayerState> 62 | 63 | This event is raised when the player leaves the session. After this the session object will never be used again. Even if the same player re-joins with the same name, they will be assigned a new state object. 64 | 65 | ```csharp 66 | VoicePlayerState.OnLeftSession += player => { 67 | Debug.Log("Player " + player.Name + " Left Session"); 68 | } 69 | ``` 70 | 71 | ## Read Only Properties 72 | 73 | ### Name : String 74 | 75 | The name of this player. This is the value in the `DissonanceComms:LocalPlayerName` property for that player. 76 | 77 | ```csharp 78 | DissonanceComms comms; 79 | VoicePlayerState aPlayer; 80 | if (aPlayer.Name == comms.LocalPlayerName) { 81 | Debug.Log(aPlayer.Name + " is the local player"); 82 | } 83 | ``` 84 | 85 | ### IsConnected : bool 86 | 87 | Get a value indicating if this player is currently in the session. 88 | 89 | ### IsSpeaking : bool 90 | 91 | Get a value indicating if this player is currently speaking 92 | 93 | ### Amplitude : float 94 | 95 | Get the current amplitude of the speech from this player. Value is in the range of 0 to 1. When using this value remember that 1 is the loudest value that can possibly be produced by the audio system - in most circumstances a speech signal will be *very* quiet (0 to 0.05 or less). 96 | 97 | ### SpeakerPriority : ChannelPriority? 98 | 99 | Get the current priority of speech from this speaker. Null if the player is not speaking. 100 | 101 | ### Rooms : ReadOnlyCollection<string> 102 | 103 | Get the list of rooms this player is currently listening to. 104 | 105 | ### PacketLoss : float? 106 | 107 | Get the estimated packet loss (0 to 1) to/from this player. May be null if the player has disconnected or packet loss has not yet been measured. 108 | 109 | ### Playback : VoicePlayback 110 | 111 | Get the `VoicePlayback` component associated with this player. May be null if Dissonance is still setting up playback for this player, or the player has left the session. 112 | 113 | ### Tracker : IDissonancePlayer 114 | 115 | Get the `IDissonancePlayer` component associated with this player. May be null if Dissonance is still setting up tracking for this player, this player does not have a `IDissonancePlayer` component, or the player has left the session. 116 | 117 | ## Properties 118 | 119 | ### Volume : float 120 | 121 | Get or set the Volume which speech from the player should be played at. The value is a direct multiplier applied to the audio and should be in the range 0 to 1. 122 | 123 | ### IsLocallyMuted : bool 124 | 125 | Get or set if this player is locally muted and will not produce any audio on the local machine. 126 | 127 | ## Methods 128 | 129 | ### GetSpeakingChannels(channels: List<RemoteChannel>) 130 | 131 | Get a snapshot of the channels you are hearing this speaker through. If they are not speaking to you then this will return no results. The `channels` parameter passed in must not be null, the list will be cleared and then filled with the current snapshot. -------------------------------------------------------------------------------- /docs/Reference/Other/VoiceSettings.md: -------------------------------------------------------------------------------- 1 | Various Dissonance audio settings can be tweaked through the VoiceSettings asset. This asset can be quickly accessed through `Window > Dissonance > Quality Settings`. 2 | 3 | !!! warning 4 | The default settings are usually the best option. Don't change these options without understanding exactly what the trade-off is. 5 | 6 | ## Persistence 7 | 8 | All of these settings can be accessed at runtime from a script through `Dissonance.Config.VoiceSettings.Instance`. Any settings which are changed by script are automatically saved into `PlayerPrefs` and override the default settings (stored in the asset). This means you can configure these settings in your menus and they will persist when your application is closed and re-opened. 9 | 10 |
11 | 12 | ![Voice Settings](../../images/VoiceSettings2.webp) 13 | 14 | ## Frame Size 15 | 16 | Controls how much audio is packed into a single network packet. Smaller frames reduce recording latency but send more packets over the network per second, which consumes more network data and slightly more CPU power. 17 | 18 | !!! warning 19 | The smallest option (`Tiny`) is not suitable for use over the internet or over a wireless network. This option should only be used in very special cases where all clients will be connected to the same wired local area network. 20 | 21 | The exact frame size at each setting is: 22 | 23 | - Tiny: 10ms (100 packets/s) 24 | - Small: 20ms (50 packets/s) 25 | - Medium: 40ms (25 packets/s) 26 | - Large: 60ms (16.6 packets/second) 27 | 28 | ## Audio Quality 29 | 30 | Controls how many bits-per-second (on average) the audio codec will use to encode audio. Higher bitrates sound better but use more network data and slightly more CPU power. 31 | 32 | The data rate used by each quality setting is: 33 | 34 | - Low: 1.25 KB/s 35 | - Medium: 2.125 KB/s 36 | - High: 3 KB/s 37 | 38 | ## Forward Error Correction 39 | 40 | Controls if the codec is using `Forward Error Correction` which improves audio quality when packets are lost. When network conditions are good this makes no difference to network data used. When network conditions are bad this slightly increases the total data used (by about 10%) and massively improves audio quality (it can almost completely mask ~5% packet loss). 41 | 42 | !!! warning 43 | It is very highly recommended to keep FEC enabled. It is a huge quality increase for a very small increase in network data usage. 44 | 45 | ## Noise Suppression 46 | 47 | Controls how much the audio pre-processor removes noise from the signal. Higher values will remove more noise but may also make speech quieter. 48 | 49 | !!! info 50 | Sounds such as people talking in the background are not noise and will not be removed by the noise suppressor. This system removes non-voice sounds such as fans hum, keyboard clatter, or fuzz from a poor quality microphone. 51 | 52 | ## Background Sound Removal 53 | 54 | Enables [RNNoise](https://jmvalin.ca/demo/rnnoise/), an ML based background sound removal system. When there is a lot of background sound (e.g. people talking, dogs barking, keyboard clatter, fan noise, loud breathing) this system will remove it, but will distort speech much more than the basic `Noise Suppression` system. Dissonance can run both noise removal systems at once, which reduces the amount of distortion present even in very noisy environments. 55 | 56 | The intensity slider limits the amount of background sound that can be removed and _also_ limits the maximum amount of distortion even in the worst case. Set it higher to cancel more noise. 57 | 58 | It is recommended to enable this system if you are building an application where there is likely to be a lot of environmental noise (e.g. a mobile app, where the user is expected to be on-the-move while talking) or an intense VR game (where the user may be breathing heavily while talking). 59 | 60 | ## Voice Detector Sensitivity 61 | 62 | The voice detector detects speech and activates [Voice Broadcast Trigger](../Components/Voice-Broadcast-Trigger.md) components configured with `Activation Mode: Voice Activation`. This settings controls a _tradeoff_ between accuracy (not activating when no one is speaking) and sensitivity (always activating when someone is speaking). 63 | 64 | A low sensitivity voice detector will not activate when there is non-speech audio (e.g. keyboard clatter), but it sometimes may not activate when there is speech (e.g. quiet speech). 65 | 66 | A high sensitivity voice detector will activate when there is speech, but it may also activate when there is non-speech audio. 67 | 68 | ## Echo Cancellation 69 | 70 | !!! info 71 | Acoustic Echo Cancellation requires some extra setup before it can be used. See [this tutorial](../../../Tutorials/Acoustic-Echo-Cancellation.html). 72 | 73 | Controls how much echo (feedback) the acoustic cancellation system attempts to remove from recorded audio. Higher values will remove more echo but may also severely distort recorded speech. 74 | 75 | Dissonance includes two completely different AEC algorithms which are used on Mobile and Desktop platforms. For Mobile Echo Cancellation the configuration value should approximately match the setup of the platform it is used on. 76 | 77 | ## Audio Duck Attenuation 78 | 79 | Controls how much received Dissonance audio will be attenuated by when any VoiceBroadcastTrigger is activated (i.e. speech is being transmitted). This can help prevent feedback of recorded audio into the microphone. The AEC system is not perfect - even if you have AEC setup and working it is still worth using audio ducking. 80 | 81 | The default value configured in Dissonance is a _very_ mild (almost imperceptible) level of audio ducking. Much smaller values can reasonably be used, particularly on mobile platforms or VR headsets where feedback (due to speakers and microphones in close proximity) is a much more common problem. -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: "Dissonance Voice Chat" 2 | repo_url: "https://github.com/Placeholder-Software/Dissonance" 3 | repo_name: "Issue Tracker" 4 | site_url: https://placeholder-software.co.uk/dissonance/docs/ 5 | site_favicon: "dissonance.png" 6 | google_analytics: 7 | - UA-46722926-2 8 | - auto 9 | copyright: "Placeholder Software" 10 | theme: 11 | name: material 12 | include_sidebar: false 13 | palette: 14 | scheme: slate 15 | primary: light blue 16 | features: 17 | - navigation.instant 18 | - toc.integrate 19 | icon: 20 | repo: fontawesome/brands/github 21 | favicon: dissonance.png 22 | extra: 23 | social: 24 | - icon: fontawesome/brands/twitter 25 | link: https://twitter.com/placeholdersoft 26 | - icon: fontawesome/brands/discord 27 | link: https://discord.gg/8dKpP5W 28 | - icon: fontawesome/brands/github 29 | link: https://github.com/Placeholder-Software/Dissonance 30 | extra_css: 31 | - css/pygment_tweaks.css 32 | - css/header_tweaks.css 33 | use_directory_urls: false 34 | copyright: "Placeholder Software" 35 | markdown_extensions: 36 | - attr_list 37 | - admonition 38 | - pymdownx.superfences 39 | - pymdownx.highlight 40 | - toc: 41 | permalink: ⚓︎ 42 | extra_javascript: 43 | - javascript/redirector.js 44 | nav: 45 | - Home: "index.md" 46 | - "Project Setup": 47 | - "Basics/Getting-Started.md" 48 | - "Basics/Choosing-A-Network.md" 49 | - "Installation Requirements": 50 | - "Basics/Licensing.md" 51 | - "Platforms/Windows Desktop.md" 52 | - "Platforms/Windows UWP & Hololens.md" 53 | - "Platforms/Linux.md" 54 | - "Platforms/MacOS.md" 55 | - "Platforms/Android.md" 56 | - "Platforms/iOS.md" 57 | - "Platforms/Magic Leap.md" 58 | - "Platforms/Oculus OVR.md" 59 | - "Basics/Other-Integrations.md" 60 | - "Quick Start Guides": 61 | - "Mirror Networking": "Basics/Quick-Start-Mirror.md" 62 | - "Unity Netcode For GameObjects": "Basics/Quick-Start-Unity-NFGO.md" 63 | - "Forge Networking Remastered": "Basics/Quick-Start-Forge-Remastered.md" 64 | - "Dark Rift 2": "Basics/Quick-Start-DR2.md" 65 | - "Photon Unity Networking": "Basics/Quick-Start-Photon.md" 66 | - "Photon Fusion": "Basics/Quick-Start-Fusion.md" 67 | - "TNet3": "Basics/Quick-Start-TNet3.md" 68 | - "Unity Networking HLAPI": "Basics/Quick-Start-UNet-HLAPI.md" 69 | - "WebRTC Network (self contained)": "Basics/Quick-Start-PureP2P.md" 70 | - "Basic Concepts": "Basics/Introduction-To-Chat-Rooms.md" 71 | - "Introductory Tutorials": 72 | - "Push-To-Talk": "Tutorials/Push-to-Talk.md" 73 | - "Global Chat Room": "Tutorials/Global-Chat-Room.md" 74 | - "Team Chat Rooms": "Tutorials/Team-Chat-Rooms.md" 75 | - "Text Chat": "Tutorials/Text-Chat.md" 76 | - "Transmit to Player": "Tutorials/Direct-Player-Transmit.md" 77 | - "Position Tracking": "Tutorials/Position-Tracking.md" 78 | - "Position Tracking For BOLT": "Tutorials/Position-Tracking-For-Bolt.md" 79 | - "Proximity Chat": "Tutorials/Proximity-Chat.md" 80 | - "Collider Chat Rooms": "Tutorials/Collider-Chat-Room.md" 81 | - "Finding Players": "Tutorials/Player-State.md" 82 | - "Audio Mixing For Voice": "Tutorials/Audio-Mixing.md" 83 | - "Access Tokens": "Tutorials/Access-Control-Tokens.md" 84 | - "Channel Priority": "Tutorials/Channel-Priority.md" 85 | - "Channel Volume": "Tutorials/Channel-Volume.md" 86 | - "Custom AudioSource Settings": "Tutorials/Playback-Prefab.md" 87 | - "Script Controlled Speech": "Tutorials/Script-Controlled-Speech.md" 88 | - "Spatialization Plugins": "Tutorials/Spatializer-Plugin.md" 89 | - "Advanced Tutorials": 90 | - "Writing A Custom Network Integration": "Tutorials/Custom-Networking.md" 91 | - "Writing A Custom IDissonancePlayer": "Tutorials/Custom-Position-Tracking.md" 92 | - "Writing A Custom Microphone Capture System": "Tutorials/Custom-Microphone-Capture.md" 93 | - "Direct Access To Recorded Audio": "Tutorials/UsingIMicrophoneSubscriber.md" 94 | - "Using Channels": "Tutorials/Directly-Using-Channels.md" 95 | - "Acoustic Echo Cancellation": "Tutorials/Acoustic-Echo-Cancellation.md" 96 | - "Server Scripting API": "Tutorials/Server-Admin-API.md" 97 | - Reference: 98 | - Components: 99 | - "Voice Broadcast Trigger": "Reference/Components/Voice-Broadcast-Trigger.md" 100 | - "Voice Receipt Trigger": "Reference/Components/Voice-Receipt-Trigger.md" 101 | - "Voice Proximity Broadcast Trigger": "Reference/Components/Voice-Proximity-Broadcast-Trigger.md" 102 | - "Voice Proximity Receipt Trigger": "Reference/Components/Voice-Proximity-Receipt-Trigger.md" 103 | - "Dissonance Comms": "Reference/Components/Dissonance-Comms.md" 104 | - Audio: 105 | - "Voice Settings": "Reference/Audio/VoiceSettings.md" 106 | - "IMicrophoneCapture": "Reference/Audio/IMicrophoneCapture.md" 107 | - "IMicrophoneSubscriber": "Reference/Audio/IMicrophoneSubscriber.md" 108 | - "BaseMicrophoneSubscriber": "Reference/Audio/BaseMicrophoneSubscriber.md" 109 | - Networking: 110 | - "Network Protocol": "Reference/Networking/Network-Protocol.md" 111 | - "IServerClientState": "Reference/Networking/IServerClientState.md" 112 | - Other: 113 | - "Voice Settings": "Reference/Other/VoiceSettings.md" 114 | - "Rooms": "Reference/Other/Rooms.md" 115 | - "RoomChannels": "Reference/Other/RoomChannels.md" 116 | - "RoomChannel": "Reference/Other/RoomChannel.md" 117 | - "PlayerChannels": "Reference/Other/PlayerChannels.md" 118 | - "PlayerChannel": "Reference/Other/PlayerChannel.md" 119 | - "TextChat": "Reference/Other/TextChat.md" 120 | - "VoicePlayerState": "Reference/Other/VoicePlayerState.md" 121 | - "RemoteChannel": "Reference/Other/RemoteChannel.md" -------------------------------------------------------------------------------- /docs/Reference/Components/Voice-Broadcast-Trigger.md: -------------------------------------------------------------------------------- 1 | # Voice Broadcast Trigger 2 | 3 | The Voice Broadcast Trigger controls when and where the local voice data is sent to. 4 | 5 | ![Voice Broadcast Trigger Inspector](../../images/VoiceBroadcastTrigger_SectionsOverview.png "Voice Broadcast Trigger Inspector") 6 | 7 | ## Channel Type 8 | 9 | This section controls which channel voice data will be sent to with this trigger. There are three channel type options, which one you choose will change the rest of the channel type UI to match. Channel type can be set from scripts by modifying the `ChannelType` property. 10 | 11 | ![Voice Broadcast Trigger - Channel Type](../../images/VoiceBroadcastTrigger_Section_ChannelType.png) 12 | 13 | #### Channel Type : Room 14 | 15 | When using the "Room" channel type broadcaster sends voice to the specified room (a single room may have multiple speakers and multiple listeners). Available rooms are listed in a dropdown box and new rooms may be added by clicking the "Config Rooms" button. The target room name can be set from scripts by modifying the `RoomName` property. 16 | 17 | #### Channel Type : Player 18 | 19 | When set to "Player" the broadcaster sends voice directly to the specified player. The inspector will show a text box to enter the name of the player to send to. The target player name can be configured from a script by modifying the `PlayerId` field. 20 | 21 | To get the names of other players inspect the DissonanceComms component at runtime - when in a session it will show a list of all players in the session. To get the name of players by script enumerate the `DissonanceComms:Players` property. 22 | 23 | #### Channel Type : Self 24 | 25 | If you have set up [Position Tracking](../../Tutorials/Position-Tracking.md) then your player object will have an `IDissonancePlayer` component which identifies it to Dissonance. You can take advantage of this to send directly to players without having to know their name. When set to "Self" the broadcast component will look for an `IDissonancePlayer` component in this GameObject or any ancestor and will send directly to that player. 26 | 27 | ## Channel Metadata 28 | 29 | This section controls which metadata is sent along with the channel. 30 | 31 | ![Voice Broadcast Trigger - Channel Metadata](../../images/VoiceBroadcastTrigger_Section_ChannelMetadata.png) 32 | 33 | #### Use Positional Data 34 | 35 | This determines whether the playback of the data sent through this broadcaster should use 3D audio playback (i.e. voice will sound as if it is coming from a certain position in space). Positional audio requires some additional setup (but does not use *any* additional CPU or network bandwidth at all when enabled). See the [Position Tracking](../../Tutorials/Position-Tracking.md) tutorial for information about how to set up your project for position tracking of player objects. This option can be set from a script by modifying the `BroadcastPosition` field. 36 | 37 | #### Priority 38 | 39 | This determines the priority which this voice has for playback. Everyone who receives audio will compare the priority of all the audio streams they are receiving and will only play out the streams with the highest priority. 40 | 41 | "None" is a special value which indicates that this broadcast trigger is setting no particular priority - the default priority for this player will be used instead. The default priority is set on the DissonanceComms component with the `PlayerPriority` property (if you do not set it it will have the priority `Default`). The priority values have this order: 42 | 43 | 1. Low 44 | 2. Default 45 | 3. Medium 46 | 4. High 47 | 48 | #### IsMuted : bool 49 | 50 | When set to `true` this trigger will never activate. 51 | 52 | This can be used to create a UI push-to-talk activated broadcast trigger - set the `Activation Mode` to `Voice Activation` and toggle the `IsMuted` property with a button. When muted by the UI no voice will be sent, when unmuted the trigger will automatically transmit when speech is detected. 53 | 54 | ## Activation Mode 55 | 56 | This section controls how the broadcast trigger decides when to send voice. There are three activation options, which one you choose will change the rest of the activation mode UI to match. Activation mode can be set from scripts by modifying the `Mode` property. 57 | 58 | ![Voice Broadcast Trigger - Activation Mode](../../images/VoiceBroadcastTrigger_Section_ActivationMode.png) 59 | 60 | #### Activation Mode : None 61 | 62 | When set to "None" the broadcaster will never broadcast any voice. 63 | 64 | #### ActivationMode : Voice Activation 65 | 66 | When set to "Voice Activation" the broadcaster will automatically transmit when voice is detected in the microphone signal. 67 | 68 | #### ActivationMode : Push To Talk 69 | 70 | When set to "Push To Talk" the broadcaster will transmit when a given input axis is chosen. You must set the name of a Unity input axis and then configure it in the Unity input manager. 71 | 72 | #### Activation Mode : Open 73 | 74 | When set to "Open" the broadcaster will constantly transmit (unless muted). 75 | 76 | #### Collider Volume Activation 77 | 78 | Using collider volume activation requires [Position Tracking](../../Tutorials/Position-Tracking.md) to be set up. When active the broadcast trigger will find a sibling physics trigger volume and will only send voice if the local player (as defined by the `IDissonancePlayer` component) is inside the volume. 79 | 80 | ## Access Tokens 81 | 82 | This section controls which [Access Tokens](../../Tutorials/Access-Control-Tokens.md) are required to send with this broadcaster. 83 | 84 | ![Voice Broadcast Trigger - Access Tokens](../../images/VoiceBroadcastTrigger_Section_AccessTokens.png) 85 | 86 | The DissonanceComms component keeps a set of tokens which the local player has. The broadcast trigger will only send voice if the player has one or more of the necessary tokens. 87 | 88 | ## Amplitude Faders 89 | 90 | This section controls the amplitude and soft fading of voice sent with this trigger. 91 | 92 | "PushToTalk Fade" (precise name depends upon which activation mode you have chosen) applies a soft fade in and out _every time_ speech is started or stopped (e.g. every time the push to talk key is pressed or released). This setting should be used with care; applying any fade in is inadvisable as it will cut off the start of what is being said. This fader can be configured from scripts by accessing the `ActivationFader` property. 93 | 94 | "Volume Trigger Fade" (only available when volume trigger is in use) applies a soft fade every time the player enters or exits the volume. This fader can be configured from scripts by accessing the `ColliderTriggerFader` property. 95 | 96 | Since there are two faders this means the trigger will have two different volumes to use, they will be multiplied together and the result is used as the actual volume value. 97 | 98 | ![Voice Broadcast Trigger - Amplitude Faders](../../images/VoiceBroadcastTrigger_Section_AmplitudeFaders.png) 99 | 100 | #### Channel Volume 101 | 102 | This controls the maximum volume of the fader (in decibels). 103 | 104 | #### Fade In Time 105 | 106 | This controls how long it takes this fader to increase volume from silence to the `Channel Volume` slider level at the start of speech. 107 | 108 | !!! warning 109 | 110 | Use with caution. This will cut off the start of speech and should rarely be used! 111 | 112 | #### Fade Out Time 113 | 114 | This controls how long it takes this fader to decrease volume from `Channel Volume` slider level to silence at the end of speech. 115 | 116 | !!! warning 117 | 118 | Use with caution. Voice will continue to be transmitted even after the user has stopped pressing the push to talk key, which could be a privacy violation. In general you should use very small values (e.g. 0.2s). 119 | 120 | 121 | 122 | -------------------------------------------------------------------------------- /docs/Basics/Choosing-A-Network.md: -------------------------------------------------------------------------------- 1 | The core Dissonance package does not include any network - instead Dissonance relies on integrations with other network systems to send and receive data. This gives you a lot of flexibility in choosing how you want voice data to be sent over the network. If none of the existing integrations are suitable for you you can also write a custom network integration. 2 | 3 | ## Free Integrations 4 | 5 | Dissonance has support for 10 network systems. All of these packages can be downloaded from the asset store for free and receive support as part of Dissonance. 6 | 7 | * [Mirror Networking](https://assetstore.unity.com/packages/slug/143290?aid=1100lJDF) 8 | * [Unity Netcode For GameObjects](https://assetstore.unity.com/packages/slug/206514?aid=1100lJDF) 9 | * [UNet HLAPI](https://assetstore.unity.com/packages/slug/143285?aid=1100lJDF) 10 | * [Dark Rift 2](https://assetstore.unity.com/packages/slug/143293?aid=1100lJDF) 11 | * [Forge Remastered](https://assetstore.unity.com/packages/slug/143286?aid=1100lJDF) 12 | * [Photon Unity networking (2)](https://assetstore.unity.com/packages/slug/143288?aid=1100lJDF) 13 | * [Photon Bolt](https://assetstore.unity.com/packages/slug/143291?aid=1100lJDF) 14 | * [TNet3](https://assetstore.unity.com/packages/tools/integration/dissonance-for-tnet3-154374?aid=1100lJDF) 15 | * [Steamworks.NET (P2P)](https://assetstore.unity.com/packages/slug/143292?aid=1100lJD) 16 | * [WebRTC Network (P2P)](https://assetstore.unity.com/packages/tools/network/webrtc-video-chat-68030?aid=1100lJDF) 17 | 18 | There are also community developed and maintained packages. 19 | 20 | * [Fish Networking](https://assetstore.unity.com/packages/tools/network/fish-net-networking-evolved-207815?aid=1100lJDF), available from [GitHub](https://github.com/LambdaTheDev/DissonanceVoiceForFishNet). 21 | * [PurrNet](https://assetstore.unity.com/packages/tools/network/purrnet-297320?aid=1100lJDF), available from [GitHub](https://github.com/BobsiUnity/PurrNet-VoiceChat). 22 | 23 | 24 | ## My Application Already Has Networking 25 | 26 | If you already have a network system set up in your application then simply sending voice through that system is the easiest option. If there is an integration package listed above for your networking system it is recommended to use that. 27 | 28 | However, if there is no available integration package then there are two options. The first option is to build your own [custom network integration](../Tutorials/Custom-Networking.md). Dissonance includes base classes which can be extended to create a new network integration relatively easily - all that is required is writing the code to send packets, receive packets and inform Dissonance about session events (leave/join/connect/disconnect etc). This requires that your networking system supports **Unreliable & Unordered** packets (e.g. UDP), TCP is **not** suitable for high quality voice chat. 29 | 30 | The second option is to establish another network session just for voice, using one of the existing integrations. Any integration can be used for this. 31 | 32 | ## My Application Does Not Have Networking 33 | 34 | If you do not have any network system already set up in your application then you can choose any supported network integration. 35 | 36 | ## Which One To Choose? 37 | 38 | ### Mirror 39 | 40 | [Mirror](https://assetstore.unity.com/packages/tools/network/mirror-129321?aid=1100lJDF) is a community built replacement for UNet. **If you are just starting out with Unity networking, this is our recommendation**. 41 | 42 | - [Discord](https://discord.gg/8pmJkfH) 43 | - Client/Server 44 | - No CCU limit 45 | 46 | ### Fish Networking 47 | 48 | [Fish Networking](https://assetstore.unity.com/packages/tools/network/fish-net-networking-evolved-207815?aid=1100lJDF) is a free open source, easy to use, feature rich networking library for Unity. Dissonance has support for Fish networking through a **community developed** integration package, [available here](https://github.com/LambdaTheDev/DissonanceVoiceForFishNet). 49 | 50 | - [Discord](https://discord.gg/fishnetworking) 51 | - [Documentation](https://fish-networking.gitbook.io/docs/) 52 | - Client/Server 53 | - No CCU limit 54 | 55 | ### PurrNet 56 | 57 | [PurrNet](https://assetstore.unity.com/packages/tools/network/purrnet-297320?aid=1100lJDF) is a free open source networking package designed for ease of use, scalability and performance. Dissonance has support for PurrNet through a **community developed** integration package, [available here](https://github.com/BobsiUnity/PurrNet-VoiceChat). 58 | 59 | - [Discord](https://discord.gg/NP9tP9Qx9R) 60 | - [Documentation](https://purrnet.gitbook.io/) 61 | - Client/Server 62 | - No CCU limit 63 | 64 | ### Unity Netcode For GameObjects 65 | 66 | [Netcode for GameObjects](https://docs-multiplayer.unity3d.com/) is the new multiplayer solution developed by Unity. 67 | 68 | - [Documentation](https://docs-multiplayer.unity3d.com/) 69 | - Client/Server 70 | - No CCU limit 71 | 72 | ### Coherence 73 | 74 | [Coherence](https://assetstore.unity.com/packages/tools/network/coherence-multiplayer-networking-301977?aid=1100lJDF) is a free to use network engine with scalable hosting. Coherence have developed their own integration package for Dissonance. 75 | 76 | - [Documentation](https://docs.coherence.io/manual/networking-voice) 77 | - Client/Server with Replication Server 78 | - Complete networking platform (scaling, matchmaking, persistence etc) 79 | 80 | ### Forge Remastered 81 | 82 | [Forge Remastered](https://assetstore.unity.com/packages/tools/network/forge-networking-remastered-38344?aid=1100lJDF) is a free networking system available on the asset store. 83 | 84 | - [Discord](https://discord.gg/5kMT7zN) 85 | - Client/Server 86 | - No CCU limit 87 | 88 | ### Dark Rift 2 89 | 90 | [Dark Rift 2](https://assetstore.unity.com/packages/tools/network/darkrift-networking-2-95309?aid=1100lJDF) is a free networking system available on the asset store. 91 | 92 | - [Discord](https://discord.gg/3dxyu3g) 93 | - Client/Server 94 | - No CCU limit 95 | - Standalone server - does not require Unity on the server 96 | 97 | ### TNet3 98 | 99 | [TNet3](https://assetstore.unity.com/packages/tools/network/networking-and-serialization-tools-tnet-3-56798?aid=1100lJDF) is a networking and serialization system available on the asset store. 100 | 101 | - [Discord](https://discord.gg/tasharen) 102 | - Client/Server 103 | - No CCU limit 104 | 105 | ### Photon Unity Networking 2 106 | 107 | [Photon Unity Networking 2](https://assetstore.unity.com/packages/tools/network/pun-2-free-119922?aid=1100lJDF) is the upgrade to the very popular Photon Unity Networking asset. It is a free (up to 20 CCU) networking system available on the asset store. 108 | 109 | - [Forum](https://forum.photonengine.com/) 110 | - Photon Cloud Hosting 111 | - CCU Limit (20 free) 112 | 113 | ### Photon Fusion 114 | 115 | [Photon Fusion](https://assetstore.unity.com/packages/tools/network/photon-fusion-267958?aid=1100lJDF) is a new network package from the developer of the very popular Photon Unity Networking asset. 116 | 117 | - [Forum](https://forum.photonengine.com/) 118 | - Photon Cloud Hosting 119 | 120 | ### WebRTC Video Chat 121 | 122 | [WebRTC Video Chat](https://assetstore.unity.com/packages/tools/network/webrtc-video-chat-68030?aid=1100lJDF) is a p2p networking, voice and video chat application. This integration uses **just the networking** part of the asset to carry Dissonance voice traffic - it does _not_ integrate in a way that allows `WebRTC Voice Chat` and `Dissonance Voice Chat` to understand each other. This can be used to quickly set up a fully p2p chat session requiring only a very lightweight session server (which carries no voice traffic). 123 | 124 | - Full P2P 125 | - No CCU limit 126 | 127 | ### UNet HLAPI 128 | 129 | UNet is the **deprecated** Unity networking system. It is **not** recommended to use this for new applications. -------------------------------------------------------------------------------- /docs/Reference/Networking/Network-Protocol.md: -------------------------------------------------------------------------------- 1 | # Network Format 2 | 3 | !!! warning "Network Protocol" 4 | Knowledge of the network format is not necessary to work with Dissonance in most cases. This documentation is only required if you want to interact with Dissonance over the network from your own non-Unity code. For example writing a Dissonance server in another language. 5 | 6 | The Dissonance network system manages three main bits of data: 7 | 8 | - Who is in the session 9 | - Who is listening to which rooms 10 | - Voice packets 11 | 12 | This document will give you an overview of how the Dissonance network system manages this data. To see the exact packet format look at `PacketWriter.cs` and `PacketReader.cs` in the Dissonance package, these structs have a method for writing/reading each different packet type. 13 | 14 | ## Glossary 15 | 16 | #### Peer 17 | Every different machine in the session is a peer. This include both the server and the client. 18 | 19 | #### Client 20 | A peer which is recording and playing voice. 21 | 22 | #### Server 23 | 24 | A which manages the organisation of the session and relays voice to clients. 25 | 26 | #### Host 27 | 28 | A peer which is both a server and a client. 29 | 30 | #### Dedicated Server 31 | 32 | A server which is not a client (i.e. no auto recording or playback). 33 | 34 | #### Reliable 35 | 36 | Some packets are sent _reliably_. This means that the packets **will** arrive at their destination in the order they were sent, there are no lost packets. This is used for all non-voice packets. 37 | 38 | #### Unreliable 39 | 40 | Some packets are sent _unreliably_. This means that the packets may be lost in transport or arrive in a different order. This is always used for voice packets. 41 | 42 | #### Frame 43 | 44 | Audio is recorded, processed and played back in _frames_, this is a buffer of 10-40ms of audio. Every frame is packed into a single network packet. 45 | 46 | #### Room 47 | 48 | A room is a type of channel which requires the listener to explicitly subscribe to the room to hear any audio sent to that room. Rooms have a name (a string) but on the network rooms are generally referred to by a 16 bit ID which is calculated by the `ToRoomId(string name)` method. 49 | 50 | ## Packet Header 51 | 52 | All packets contain a header which is used to check that the packet is valid. 53 | 54 | The first 16 bits of every Dissonance packet are a 16 bit _magic number_ `0x8BC7`. This is read from the start of the packet and if it's incorrect the packet is immediately discarded. If something goes wrong and non-Dissonance packets are sent to Dissonance this prevents them from being decoded. 55 | 56 | The next 8 bits are the packet type, this tells Dissonance how the contents of the packet should be decoded. The values used for this are defined in `MessageTypes.cs`. 57 | 58 | After that all packets (except `HandshakeRequest`) have a 32 bit session number, this is a unique number randomly generated by the server when it starts a new session. If the session number does not match the packet is immediately discarded. If something goes wrong and packets from one Dissonance session are sent to another Dissonance session this prevents them from being decoded. 59 | 60 | ## Kicking From A Session 61 | 62 | If a packet with an incorrect session number is received by the server it will send back an `ErrorWrongSession` packet to the client which contains the session number being used by the server. If the client is not using this session number it will disconnect and reconnect to the server. 63 | 64 | ## Joining A Session 65 | 66 | 1. A new client sends a `HandshakeRequest` message to the server. This tells the server the codec settings in use by this client as well as it's name. 67 | 2. The server replies with a `HandshakeResponse` message. This sends the complete state of the server to the client: 68 | 69 | - the session ID. A unique value prepended to all packets. 70 | - The client ID. A unique 16 bit ID for this client. 71 | - Client list. A list of all other clients in the session (name, codec setting, unique ID). 72 | - Room list. A list of the room names which at least one client is currently listening to. 73 | - Listeners list. A list of clients and the rooms which they are currently listening to. 74 | 75 | 3. The client replies with a `ClientState` message. This tells the server the complete state of the client: 76 | 77 | - Name 78 | - Client ID 79 | - Codec Settings 80 | - Rooms list. A list of the rooms this client is currently listening to. 81 | 82 | !!! info 83 | The `HandshakeResponse` message contains data about _all_ clients currently in the session. In a very large session this can cause a problem with oversize packets. It is valid for the server to send some/none of the client data in the initial `HandshakeResponse` packet and instead to send it in individual `ClientState` messages immediately after the `HandshakeResponse` 84 | 85 | ## Joining Or Leaving A Room 86 | 87 | The server maintains a list of which rooms every client is currently listening to. Sending a complete `ClientState` message every time a client join or leaves a room would be wasteful, instead a `DeltaClientState` message is sent. This contains: 88 | 89 | - Flag indicating `joining` or `leaving` 90 | - Client ID 91 | - Room name 92 | 93 | ## Replicating Data 94 | 95 | The update messages `ClientState` and `DeltaClientState` are sent from clients to the server, which updates it's internal state. The server also broadcasts these messages out to all clients which update their own state. This means that every client has exactly the same list of who is listening to which rooms. 96 | 97 | ## Peer To Peer 98 | 99 | It's possible for peers to communicate directly. When this is setup the metadata messages are still sent to the server but voice packets are sent directly from one client to another. 100 | 101 | To set this up a client sends a `HandshakeP2P` message to every peer which it knows how to directly contact. The `HandshakeP2P` message contains the ID of the sending client. When a client receives a `HandshakeP2P` message from another client it can take note of the connection which that message came through, send back a `HandshakeP2P` message in response over that connection, and now the two peers can communicate directly. 102 | 103 | ## Voice Packets 104 | 105 | Each client records audio, preprocesses it to improve audio quality, encodes it (using opus) and then sends the packet. The client decides who to send the packet to based on it's knowledge of who is listening to what. The client sends the voice packet via P2P to as many client as possible. The remaining packets are relayed via the server. 106 | 107 | The `VoiceData` packet contains: 108 | 109 | - Sender Client ID 110 | - 8 bit bitfield of packet flags 111 | - Sequence number. A number which can be used to put packets into the correct order 112 | - A list of channels which this voice is addressed to. For each channel: 113 | - 16 bit channel bitfield 114 | - 16 Bit channel ID 115 | - A frame of encoded audio 116 | 117 | #### Bitfield 118 | 119 | The 8 bit bitfield contains: 120 | - The MSB is always set to `1` 121 | - The remaining 7 bits contain a wrapping counter which increments every time the "channel session" changes. The "channel session" changes whenever all sending channels are closed (i.e. there is an interruption in the voice stream). 122 | 123 | ## Relayed Packets 124 | 125 | When packets cannot be sent directly with P2P they can be relayed via the server. The `ServerRelayReliable` and `ServerRelayUnreliable` packets are used for this purpose. These packets contain a list of destination client IDs and then an array of bytes. 126 | 127 | When the server receives one of these packets it sends the array of bytes out to all of the listed clients. The server will discard attempts to relay `HandshakeP2P` packets. 128 | 129 | ## Text Packets 130 | 131 | Text packets can be sent through the Dissonance session, unlike voice they are always relayed via the server. The `TextData` packet contains: 132 | 133 | - Recipient type. This indicates if the packet is targeted at a player or a room. 134 | - Sender ID. Client ID of the sender. 135 | - Recipient ID. This is either a room ID or a client ID, depending upon the recipient type. 136 | - A string of UTF8 encoded text. 137 | 138 | ## Leaving A Session 139 | 140 | When a client leaves the session the server sends a `RemoveClient` message out to all clients. This simply contains the ID of the client which is leaving the session. -------------------------------------------------------------------------------- /docs/Tutorials/Acoustic-Echo-Cancellation.md: -------------------------------------------------------------------------------- 1 | ## Acoustic Echo Cancellation 2 | 3 | When playing audio from speakers and recording audio from a nearby microphone you will often encounter problems when the microphone picks up the audio from the speakers. In a voice session a single person doing this can cause annoying echoes to be transmitted and multiple people doing this simultaneously can cause painful feedback which persists until everyone stops transmitting. This can be particularly problematic when using Voice Activation Detection (VAD) because the VAD automatically transmits back all speech it detects, causing constant echoes of everything other people say. It can also be very bad on platforms where the mic and the speaker are very close together such as VR headsets and mobile phones. Acoustic Echo Cancellation (AEC) is a system to automatically remove these echoes from the transmitted voice signal. 4 | 5 | ## How Does AEC Work? 6 | 7 | Echo is caused by sound which leaves the speaker, bounces off some of the nearby environment and re-enters the mic. The AEC filter is attached the the audio mixer on the output, this filter knows what sounds are leaving the speakers and this knowledge can be used to detect and remove that echo in the microphone preprocessor: 8 | 9 | Audio Output -> **Audio Postprocessor** -> Speakers -> Echo -> Microphone -> Audio Preprocessor 10 | 11 | The most complex part of this system is working out what the delay is between the `Audio Postprocessor` and the `Audio Preprocessor`. This is achieved automatically but it is important to understand that the AEC system can take several seconds to work out the correct delay value - until it has done this no echo will be cancelled. The AEC cannot be calculating the delay value while there is no sound being played and it will slowly "forget" the delay value during long periods of silence. 12 | 13 | In most scenarios this is not a problem - game sound effects and background music will be enough to keep the AEC synchronised with a suitable delay value. However if you are encountering problems with the AEC not working you should consider adding some sound effects for the AEC to process - e.g. a short jingle when a user joins a session, or ringing sound when joining a session. 14 | 15 | ## AEC Setup 16 | 17 | ### 1. Audio Postprocessor 18 | 19 | Attach the `Dissonance Echo Cancellation` audio filter to the very last [audio mixer](https://docs.unity3d.com/Manual/AudioMixer.html) in the mixing system and disable the `Auto Mixer Suspend` option for this mixer. If you were not already using audio mixers simply create a new mixer in `Window > Audio Mixer` and attach the filter to that. 20 | 21 | ![Audio Mixer With AEC Filter](../images/AudioMixer_WithAecFilter.png) 22 | 23 | ### 2. Route Non-Voice Audio 24 | 25 | The filter will only process audio which passes through the mixer it is attached to - how to achieve this depends on what kind of audio mixing system you already had setup before using AEC. 26 | 27 | - If you were already using audio mixers: ensure that **all** the mixers eventually pass through the mixer with the `Dissonance Echo Cancellation` filter attached. 28 | - **If you were not already using mixers** then set **all** `AudioSource` components to output to the new mixer you created in the previous step. 29 | 30 | You can check that you have done this correctly by running the game and watching the audio mixer window. The dB meter on the mixer should move when non-voice audio is playing. 31 | 32 | ![Audio Source With Output Highlighted](../images/AudioSource_OutputHighlighted.png) 33 | 34 | ### 3. Route Voice Audio 35 | 36 | Voice audio also needs to be re-routed to pass through the mixer with the filter attached. To change where voice audio is sent you need to create a custom [playback prefab](../Tutorials/Playback-Prefab.md). Create a prefab with a `VoicePlayback` component and an `AudioSource` component. Set the output of the AudioSource to the correct mixer. Finally drop the prefab into the `Playback Prefab` field of the `Dissonance Comms` component. 37 | 38 | ![Playback Prefab With Output Highlighted](../images/PlaybackPrefab_OutputHighlighted.png) 39 | 40 | If you were already using audio mixers then you may want to consider creating a mixer specifically for voice and outputting this mixer to the root mixer. This will allow you to attach sound effects specifically to voices. 41 | 42 | If you were not using audio mixers then you should just send the voice data to the mixer you created in step 1. 43 | 44 | ### 4. AEC Configuration 45 | 46 | Now that all the audio is routed to pass through the filter AEC can run. Open the Dissonance quality settings menu `Window > Dissonance > Quality Settings` to set the amount of echo suppression applied. Desktop platforms and mobile platforms use different AEC systems internally and are configured separately. Dissonance will automatically switch to using the mobile AEC (AECM) when a mobile platform is detected. 47 | 48 | ![AEC Settings Inspector](../images/AecSettings.png) 49 | 50 | These settings can be set in the editor - they will be saved into an asset and used as the default values at runtime. They can be changed at runtime by accessing the `VoiceSettings` class: 51 | 52 | ```csharp 53 | //Change amount of AEC applied on Desktop 54 | VoiceSettings.Instance.AecSuppressionAmount = AecSuppressionLevels.Moderate; 55 | 56 | //Change amount of AEC applied on Mobile 57 | VoiceSettings.Instance.AecmRoutingMode = AecmRoutingMode.Speakerphone; 58 | ``` 59 | 60 | Only the two settings shown above can be changed while Dissonance is running, doing so will trigger a reset of the audio input system (causing a small hitch in transmitted audio). Changes to any other AEC related settings will be ignored until the next time the audio input system is reset (e.g. by changing the settings above). 61 | 62 | You should start with low AEC settings and ask the user to increase them if echo becomes a problem - excessive levels of AEC can very badly distort voices. 63 | 64 | ### 5. Testing AEC 65 | 66 | Once you have set all of this up you may want to test that AEC is working as intended. To do so simply add an `AudioSource` component to your scene playing some loud music - make sure it's routed through the correct mixer! Now run the scene in the editor and select the filter attached to the audio mixer, this will show a status screen for the AEC: 67 | 68 | ![AEC Status Inspector](../images/AecStatus.png) 69 | 70 | When the filter first starts all of the stats will be labelled as "initialising...", this indicates that the filter has not yet converged and will not yet be removing any echo. Once the AEC is running and has converged remote speakers in the session should not be able to hear the music you are playing. In our own tests we have had music playing loudly enough to drown out voices but even that was still cancelled! 71 | 72 | ### 6. Other Improvements 73 | 74 | AEC is **not** a perfect system and there will usually be some echo which is not cancelled out. Certain conditions such a high background noise or a very large delay (e.g. Bluetooth headphones/microphones) can make this much worse or even not work at all. Therefore it's important to have other mitigations to reduce the impact of bad echo. 75 | 76 | [Voice Ducking](../Reference/Other/VoiceSettings#audio-duck-attenuation) automatically reduces the volume of received voices when voice is being transmitted. This reduces the chance of feedback occurring since incoming voices are quieter and less likely to be picked up by the mic. 77 | 78 | [Audio Ducking](../Tutorials/Audio-Mixing#volume-ducking) can be set up in the Unity mixer to reduce the volume of all non-voice sounds when any voice audio is being received. Because the other sound effects are quieter this allows you to reduce the volume of all voices, reducing the chance of the mic recording them. 79 | 80 | [Background Sound Removal](../Reference/Other/VoiceSettings#background-sound-removal) automatically removes non-voice sounds from the microphone signal. This cannot fix echoed voices, but it can improve other non-voice sounds that are recorded by the microphone. 81 | 82 | A [Low Pass Filter](https://docs.unity3d.com/Manual/class-AudioLowPassFilter.html) can be set up in the Unity mixer on the received voices, with a `Cutoff Frequency` of around 6000Hz. This is above the range of normal human speech. If the worst kind of feedback happens (very high pitched squealing) this will reduce the volume and prevent it from getting any worse. 83 | 84 | ## Fixing `Audio effect Dissonance Echo Cancellation could not be found.` Error (iOS) 85 | 86 | To fix this problem on iOS you must manually register the audio effect with the Unity audio pipeline. 87 | 88 | 1. Download `AudioPluginInterface.h` from [the Unity native audio plugin SDK](https://github.com/Unity-Technologies/NativeAudioPlugins) and add it to your XCode project. 89 | 2. add `#import "AudioPluginInterface.h";` to `UnityAppController.mm` in XCode. 90 | 3. Find the `preStartUnity` method and add the line `UnityRegisterAudioPlugin(&UnityGetAudioEffectDefinitions);` 91 | 92 | If this does not fix the issue, please add a comment to [this issue](https://github.com/Placeholder-Software/Dissonance/issues/80). -------------------------------------------------------------------------------- /docs/Reference/Components/Dissonance-Comms.md: -------------------------------------------------------------------------------- 1 | # Dissonance Comms 2 | 3 | The Dissonance Comms component is the central place to configure Dissonance. There must be an active one within the scene for Dissonance to work. 4 | 5 | ![Dissonance Comms Inspector](../../images/DissonanceComms_Inspector.png "Dissonance Comms Inspector") 6 | 7 | ## Playback Prefab 8 | 9 | This is a prefab for the audio playback system. For every remote player who is in the voice session Dissonance will instantiate this prefab, and use it to play the voice from that player. If left blank the default playback prefab included with Dissonance will be used. Read more about the playback prefab and how you can customise it [here](../../Tutorials/Playback-Prefab.md). 10 | 11 | ## Mute 12 | 13 | This will prevent the local player from sending any voice. 14 | 15 | ## Access Tokens 16 | 17 | This is the set of [access tokens](../../Tutorials/Access-Control-Tokens.md) which the local player has. 18 | 19 | ## Voice Settings 20 | 21 | Clicking this button opens an inspector where audio settings relating to voice may be changed. 22 | 23 | ## Configure Rooms 24 | 25 | Clicking this button opens an inspector where rooms can be created or deleted. 26 | 27 | ## Diagnostic Settings 28 | 29 | Clicking this button opens an inspector where Dissonance diagnostic settings may be changed (e.g. log levels). 30 | 31 | # Scripting 32 | 33 | Dissonance Comms is also the central place to access Dissonance from scripts. 34 | 35 | ## Readonly Properties 36 | 37 | ### IsNetworkInitialised : bool 38 | 39 | Indicates if the Dissonance network has been successfully initialised yet. 40 | 41 | ### Rooms : Rooms 42 | 43 | An object which exposes various properties and methods to do with rooms the local player is listening to. See further documentation [here](../Other/Rooms.md). 44 | 45 | ### PlayerChannels : PlayerChannels 46 | 47 | An object which exposes various properties and method to do with players the local player is speaking to. See further documentation [here](../Other/PlayerChannels.md). 48 | 49 | ### RoomChannels : RoomChannels 50 | 51 | An object which exposes various properties and methods to do with room the local player is speaking to. See further documentation [here](../Other/RoomChannels.md). 52 | 53 | ### Text : TextChat 54 | 55 | An object which exposes various properties and methods to do with text chat. See further documentation [here](../Other/TextChat.md). 56 | 57 | ### Players : ReadOnlyCollection<VoicePlayerState> 58 | 59 | A list of `VoicePlayerState` objects, one for each remote player currently in the session. See further documentation on `VoicePlayerState` [here](../Other/VoicePlayerState.md). 60 | 61 | ### TopPrioritySpeaker : ChannelPriority 62 | 63 | The highest [priority](../../Tutorials/Channel-Priority.md) of all remote players currently speaking in the session. 64 | 65 | ### Tokens : IEnumerable<string> 66 | 67 | The set of [tokens](../../Tutorials/Access-Control-Tokens.md) which the local player possesses. 68 | 69 | ### MicrophoneCapture : IMicrophoneCapture 70 | 71 | The microphone capture object which Dissonance is currently using. This may be null if Dissonance has not initialised yet or if the local instance is a dedicated server. 72 | 73 | --- 74 | ## Properties 75 | 76 | ### LocalPlayerName : String 77 | 78 | The name of the local player, this will be initialised to a unique ID per player when Dissonance starts. This may not be changed once Dissonance has started. 79 | 80 | ### PlayerPriority : ChannelPriority 81 | 82 | The [priority](../../Tutorials/Channel-Priority.md) of the local player, if a channel is opened with no priority set this priority will be used as a default. 83 | 84 | ### MicrophoneName : string 85 | 86 | Get or set the name of the microphone to use to capture voice. This may be changed at any time, if the microphone has already begun recording with a different name it will be reset to use the new name. 87 | 88 | ### PlaybackPrefab : VoicePlayback 89 | 90 | Get or set the playback prefab which Dissonance will use to play back remote voices. This may not be changed once Dissonance has started. 91 | 92 | ### IsMuted : bool 93 | 94 | Get or set if the local player is muted (i.e. prevented from sending any voice transmissions). 95 | 96 | ### IsDeafened : bool 97 | 98 | Get or set if the local player is deafened (i.e. prevented from hearing any remote voice transmissions). 99 | 100 | --- 101 | ## Events 102 | 103 | ### OnPlayerJoinedSession : event Action<VoicePlayerState> 104 | 105 | This event runs whenever a new player joins the Dissonance voice chat session. It is passed the object which represents the new player. 106 | 107 | ### OnPlayerLeftSession : event Action<VoicePlayerState> 108 | 109 | This event runs whenever a player leaves the Dissonance voice chat session. It is passed the object which represents the player. The object will never be touched by Dissonance again - if the player rejoins a new object will be created for them. 110 | 111 | ### OnPlayerStartedSpeaking : event Action<VoicePlayerState> 112 | 113 | This event runs whenever a remote player begins speaking in a channel which the local player can hear. 114 | 115 | ### OnPlayerStoppedSpeaking : event Action<VoicePlayerState> 116 | 117 | This event runs whenever a remote player stops speaking in all channels which the local player can hear. 118 | 119 | This may not indicate that the remote player has actually stopped talking completely, it is possible that the local player simply stopped listening. For example if you are listening to _Room A_ and they are talking to _Room A_ and _Room B_, then when you stop listening to _Room A_ you will receive this event (even though they are still talking to _Room B_) because they have stopped speaking _from your point of view_. 120 | 121 | ### OnPlayerEnteredRoom : event Action<VoicePlayerState, string> 122 | 123 | This event runs whenever a remote player begins listening to a new room. It is passed the object which represents the player and the name of the room. 124 | 125 | ### OnPlayerExitedRoom : event Action<VoicePlayerState, string> 126 | 127 | This event runs whenever a remote player stops listening to a room. It is passed the object which represents the player and the name of the room. 128 | 129 | ### LocalPlayerNameChanged : event Action<string> 130 | 131 | This event runs whenever the local player name is changed. Local player name may only be changed before the DissonanceComms component has been started. 132 | 133 | ### TokenAdded : event Action<string> 134 | 135 | An event which runs whenever a token is added to the local player. 136 | 137 | ### TokenRemoved : event Action<string> 138 | 139 | An event which runs whenever a token is removed from the local player. 140 | 141 | --- 142 | ## Methods 143 | 144 | ### FindPlayer(string name) : VoicePlayerState 145 | 146 | Attempt to find the player with the given Dissonance ID. Will return null if no such player can be found. 147 | 148 | ### SubscribeToVoiceActivation(IVoiceActivationListener) 149 | 150 | Subscribes the given listener object to the voice activation detector (VAD) for the local player. When VAD detects speech the `VoiceActivationStart` method will be called. When the VAD stops detecting speech the `VoiceActivationStop` method will be called. 151 | 152 | ### UnsubscribeFromVoiceActivation(IVoiceActivationListener) 153 | 154 | Unsubscribes a previously subscribed listener object from the VAD. 155 | 156 | ### SubscribeToRecordedAudio(IMicrophoneSubscriber) 157 | 158 | Subscribes the given listener object to the microphone recorded audio _after_ it has been preprocessed. This will receive all audio recorded by the mic whether or not it is being sent over the network. Use `DissonanceComms.RoomChannels.Count` and `DissonanceComms.PlayerChannels.Count` to determine if the audio is being sent anywhere. 159 | 160 | ### UnsubscribeFromRecordedAudio(IMicrophoneSubscriber) 161 | 162 | Unsubscribes a previously subscribed listener object from the microphone audio stream. 163 | 164 | ### TrackPlayerPosition(IDissonancePlayer) 165 | 166 | Begins [position tracking](../../Tutorials/Position-Tracking.md) for the player represented by the given object. 167 | 168 | ### StopTracking(IDissonancePlayer) 169 | 170 | Stops [position tracking](../../Tutorials/Position-Tracking.md) for the player represented by the given object. 171 | 172 | ### AddToken(string) 173 | 174 | Adds a [token](../../Tutorials/Access-Control-Tokens.md) to the local player. 175 | 176 | ### RemoveToken(string) : bool 177 | 178 | Removes a [token](../../Tutorials/Access-Control-Tokens.md) from the local player and returns a bool indicating if that token was removed. This will return false if the player never had the token in the first place. 179 | 180 | ### ContainsToken(string) : bool 181 | 182 | Returns a boolean value indicating if the local player has the [token](../../Tutorials/Access-Control-Tokens.md) with the given name. 183 | 184 | ### HasAnyToken(TokenSet) : bool 185 | 186 | Returns a boolean value indicating if the local player has *any* of the [tokens](../../Tutorials/Access-Control-Tokens.md) in the given TokenSet. 187 | 188 | ### ResetMicrophoneCapture 189 | 190 | Forces a complete restart of the audio capture pipeline. 191 | 192 | ### GetMicrophoneDevices(List output) 193 | 194 | Get a list of available microphones. Microphone names will be added to the `output` list. --------------------------------------------------------------------------------