-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathDocumentation.txt
156 lines (102 loc) · 9.15 KB
/
Documentation.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
::v3.3::11.2o23::2021.3.0::
.: General usage notes and concepts overview :.
================================================================================
(turn on Word Wrap in your IDE/editor for possibly more readable formatting)
This file is more of an overview, with generic components - for each specific topic please see 'DocumentationNNN_[topic].txt' file/s next to this one.
Note: >> When working with audio it's often very useful to turn on 'Run In Background' in player settings to keep audio running when switching out of the Editor.
(For 2022 and up -> please enable non secure HTTP downloads in 2022 (and up) Player settings in order to use links in the demo
| Go to Edit -> Project Settings -> Player -> Other Settings > Configuration and set 'Allow downloads over HTTP' to 'Always allowed'. Alternatively, use your own secure (HTTPS) links only.)
- as mentioned in !!README1ST!!, the asset by default populates Editor BuildSettings scene list with all demo scenes and copies all demo assets into 'StreamingAssets\AudioStream';
you can turn this off by unchecking 'copyDemoScenesToBuildSettings' on 'AudioStream\Demo\_Support\Editor\AudioStreamDemoMenuDef' configuration object.
-------------------------
.: Source code license :.
-------------------------
you can use any part of this asset and its source code in any and all of your projects - just don't publish it for public access
If you customize significant portions of the source infrastructure, please attribute where the inspiration came from - i.e. from this asset, in the form:
"Uses AudioStream Unity package (c) 2016-2024 Martin Cvengros, https://r618.github.io/"
--------------------------------------------------------------------------------
================================================================================
Scripting API:
================================================================================
For scripting please refer to demo scenes in Demo\[component group]\ folder/s:
- each component has a specific demo scene set up with its intended usage
- each demo scene contains a GameObject with script ending with 'Demo' with scene UX and asset's component(s) references
- these single files in general illustrate how to use each component's API the intended way
- most important/relevant sections are commented
- it's worth paying attention esp. to initialization usually found in Start (coroutine), and events where they are handled
================================================================================
Devices config:
================================================================================
Devices configuration across the whole package was brought into a single place in
'AudioStream\Scripts\Resources\DevicesConfiguration'
scriptable object.
(Resources folder is used for config to be available also at runtime)
Each entry corresponds to given output id in that order as seen by FMOD during initialization
- config for each (input/output) device consists of several fields, for more details on each refer to its Editor tooltip
The asset has configured settings for output #0 as an example
- since it is populated just with default values, the output's properties will be unchaged (as set by OS by default)
For custom/RAW speaker mode see also FMOD documentation:
https://www.fmod.com/docs/2.02/api/core-api-common.html#fmod_speakermode
and https://www.fmod.com/docs/2.02/api/core-api-channelcontrol.html#channelcontrol_setmixmatrix
- good place to call setMixMatrix on opened channel is in 'OnPlaybackStarted' event.
- max. number of speakers is MAX_CHANNEL_WIDTH = 32; - see also https://www.fmod.com/docs/2.02/api/core-api-common.html#fmod_max_channel_width
Note:
ASIO has separate buffer settings (which have to correspond to configured ASIO buffer), but the rest of the settings are used also for it.
Refer to 'Documentation070_ASIO.txt' for more.
================================================================================
IL2CPP builds and building with turned off IL2CPP runtime checks:
================================================================================
Code running most tight audio loops can be optionally built with null, array bounds and division by zero checks turned off for IL2CPP builds (which is generally recommended but it's advisable to verify that build is running correctly with them being turned off first)
The needed attributes for this are included in the package, but you are advised to verify this, i.e. check for your Unity version, see e.g. https://docs.unity3d.com/2018.4/Documentation/Manual/IL2CPP-CompilerOptions.html (and your respective Editor version) how to do that.
The file 'Il2CppSetOptionAttribute.cs' must be placed into project's 'AudioStream/Support' folder (or any of its subfolders) - must be part of the 'AudioStreamSupport' assembly definition
- if project doesn't have ENABLE_IL2CPP compiler define added already, add ENABLE_IL2CPP to Scripting Define Symbols in Player Settings
================================================================================
Local disk cache:
================================================================================
Customizable via 'AudioStreamRuntimeSettings' scriptable object in 'AudioStream\Support\Resources'
- 'Download Cache Path' location for storing original compressed stream, which can be saved / played later offline via 'AudioStream' based on its Url.
Defaults to Application.persistentDataPath if not set/empty.
- 'Temporary Directory Path' stores intermediary uncompressed audio mainly for AudioClip creation by AudioStreamRuntimeImport and AudioStreamMemory components.
Defaults to Application.temporaryCachePath if not set/empty.
Both can be either full or relative directory paths.
================================================================================
GOAudioSaveToFile component:
================================================================================
- utility script that allows automatic or manual saving of audio being played on a Game Object to a file in WAV PCM16 format
- file is saved into StreamingAssets, except on iOS, Android and WSA where Application.persistentDataPath is used (also see https://docs.unity3d.com/ScriptReference/Application-persistentDataPath.html)
You can drive it also externally by passing write data yourself - just uncheck useThisGameObjectAudio in that case and call 'AddToSave' on it periodically [at OnAudioFilterRead rate] after it's started via 'StartSaving'.
On iOS you can enable 'Application supports iTunes file sharing' entitlement to (more easily) retrieve/access the application data container and saved files from desktop.
================================================================================
Projects with disabled Unity audio:
================================================================================
Asset will properly run with Unity audio disabled in Project Settings, except all AudioSource related functionality won't work;
All FMOD stuff will function properly though, so components which don't rely on Unity AudioSource will function as usual -
such as all AudioStreamMinimal, MediaSource, and Resonance components
- Unity will print an error message when accessing its certain Audio features (such as AudioSettings.outputSampleRate)
and these are left as message to user that they probably shouldn't be used
================================================================================
For more details about all components please refer to each respective file in _Docs folder:
- 'Documentation000_audio_streaming':
- main playback/streaming components: AudioStream, AudioStreamMinimal, AudioStreamRuntimeImport, AudioStreamMemory
- 'Documentation010_recording_and_inputs':
- streaming from any available system recording input: AudioStreamInput, AudioStreamInput2D, ResonanceInput, and 'AudioStream InputDevice' Audio Mixer effect
- 'Documentation020_system_outputs':
- playing Unity audio on different available system outputs: AudioSourceOutputDevice, OutputID on AudioStreamMinimal, and 'AudioStream OutputDevice' Audio Mixer effect
- 'Documentation021_channels_separation':
- playing on different channels of an output: AudioSourceOutputDevice and MediaSourceOutputDevice
- separating playback and input channels: (originally demo scripts) AudioStreamInputChannelsSeparation, AudioSourceChannelsSeparation, AudioClipChannelsSeparation
- 'Documentation030_3D_spatialisation':
- Unity spatialization (Spatial Blend) w/ AudioStream and AudioStreamInput
- Resonance based 3D spatialization components: ResonanceSource, ResonanceSoundfield, ResonanceInput
- 'Documentation031_audiolisteners':
- Resonance based Audio Listener for Unity AudioSources
- AudioStreamListener and AudioStreamListenerAudioSource components
- 'Documentation040_Icecast':
- IcecastSource for AudioSource -> Icecast mountpoint
- 'Documentation050_LAN_source_client':
- AudioSources connector over LAN: AudioStreamNetMQSource/AudioStreamNetMQClient and AudioStreamOscSource/AudioStreamOscClient
- 'Documentation060_mobiles':
- AudioStreamInput_iOS_ExternalDevicesDemo for capturing external devices on iOS, incl. e.g. Bluetooth headphones/microphones
- iOS and Android background running notes
- 'Documentation070_ASIO':
- config & running ASIO enabled system