Getting started

Welcome to audioware book !

Audioware is a native plugin to play custom audios in Cyberpunk 2077, without REDmod.

It's built with emphasis on getting you going fast, providing sensible defaults and seamless integration with the game while not compromising on performances.

Here's the simplest way to test it out in under 5min.

⬇️ Install

• grab Audioware latest release and unzip it in root game folder.
• make sure you have both Codeware 1.11.1+ and TweakXL 1.10.2+ installed too.

📄 Define audios

Create a folder e.g. MyMod for your mod, located in either depot:

• under mods\MyMod
• or r6\audioware\MyMod but not both !

Create a manifest e.g. audios.yml.

In its simplest form, here's how it looks like:

version: 1.0.0
sfx:
  my_custom_audio: some.mp3 # accepts most common formats like .wav / .ogg / .mp3 / .flac

♬⋆.˚ Use in-game

GameInstance.GetAudioSystem(game).Play(n"my_custom_audio");

If you want to dive in directly, head over to How to use? for more.

Concept

Out-of-the-box, Cyberpunk 2077's vanilla¹ audio engine is built on top of Audiokinetic's WWise which is a professional-grade audio software and tools suite.

Audioware does not make any use of it and it has almost no control over it.

Here's how Cyberpunk 2077 is designed, in an overly simplified way.

But the reality is that, when you choose this path on one side you get native² integration which is great, but on the other you then need to do everything as both WWise and the game does. Not even mentioning that you actually will have to learn how CDPR works with WWise, which is not always standard.

Professional all-in-one softwares like Audiokinetic can be dauting to use when unfamiliar and quickly become an entry-skills barrier³ for newcomers who would simply like to add sounds, play around with them, have fun and come up with an interesting mod.

The audio parameters it exposes are very cool, but as far as I remember you can't seamlessly switch from one to another, and if you want multiple parameters per sound you basically have to duplicate them as many times.

Last but not least, I regularly got players complaining about it becoming overly slow when (too?) many mods use it, and it does not seem particularly appreciated among player base.

And this how Audioware was initially born as a simple proof-of-concept in 4ddicted, another mod of mine. Until other modders started to notice that it worked pretty well and asked me to turn into a fully integrated native plugin.

Audioware actually uses a second alternate audio engine named kira, alongside vanilla one.

It then does integrate seamlessly, creating the illusion that there's only one and unique audio environment.

Here is, once again in an overly simplified way, how it works:

But let's process to next chapter to see how it can be used, and what it can currently do for you.

How to use?

In Getting started we already saw that adding custom sounds for Cyberpunk 2077 with Audioware literally boils down to 2 steps:

1. define your audios in Manifest(s): see how to further describe your audio assets along optional settings and metadata.
2. play them in-game with scripting API: using CET or Redscript to control how / when they get played, stopped, switched, etc.

All audios have some automations built-in, that you can read about in Integration

Manifest

A manifest is a simple YAML¹ file to describe your sounds. Audioware then use them to build sounds banks on game startup.

Let's take a closer look at a Manifest's anatomy.

Anatomy

A manifest is a .yml¹ file located in a folder named after your mod inside one of 2 depots.

It expects a version and sections like sfx, onos, voices or music.

It must be defined:

• in a folder named after your mod (e.g. mods\MyMod) itself located inside any valid depot (mods or r6\audioware),
• alongside audio files: files can be located in sub-folders, at your discretion.

Each section contains one or multiple audio ID(s) which points to an audio file path.

When using a simple audio file, you can write it inline.

version: 1.0.0
# ⬇️ section
sfx:
# ⬇️ audio ID      ⬇️ audio file path
  my_custom_audio: some.mp3

But you can also write nested properties for settings:

version: 1.0.0
sfx:
  my_custom_audio:
    file: some.mp3 
    settings:
      volume: 4.0 # 4 times louder!

All audio accepts multiple optional settings.

Supported audio formats

Audioware supports the following formats:

• .wav
• .ogg
• .mp3
• .flac

$ just analyze C:\\Development\\modding-cyberpunk\\4ddicted\\archive\\source\\archive\\base\\localization\\common\\vo\\civ_mid_m_85_mex_30_mt_vista_del_rey_f_1ed3f72f92559000.wem

ffprobe -i 'C:\Development\modding-cyberpunk\4ddicted\archive\source\archive\base\localization\common\vo\civ_mid_m_85_mex_30_mt_vista_del_rey_f_1ed3f72f92559000.wem' -show_format

ffprobe version 6.0-essentials_build-www.gyan.dev Copyright (c) 2007-2023 the FFmpeg developers
  built with gcc 12.2.0 (Rev10, Built by MSYS2 project)
  configuration: --enable-gpl --enable-version3 --enable-static --disable-w32threads --disable-autodetect --enable-fontconfig --enable-iconv --enable-gnutls --enable-libxml2 --enable-gmp --enable-lzma --enable-zlib --enable-libsrt --enable-libssh --enable-libzmq --enable-avisynth --enable-sdl2 --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxvid --enable-libaom --enable-libopenjpeg --enable-libvpx --enable-libass --enable-libfreetype --enable-libfribidi --enable-libvidstab --enable-libvmaf --enable-libzimg --enable-amf --enable-cuda-llvm --enable-cuvid --enable-ffnvcodec --enable-nvdec --enable-nvenc --enable-d3d11va --enable-dxva2 --enable-libmfx --enable-libgme --enable-libopenmpt --enable-libopencore-amrwb --enable-libmp3lame --enable-libtheora --enable-libvo-amrwbenc --enable-libgsm --enable-libopencore-amrnb --enable-libopus --enable-libspeex --enable-libvorbis --enable-librubberband
  libavutil      58.  2.100 / 58.  2.100
  libavcodec     60.  3.100 / 60.  3.100
  libavformat    60.  3.100 / 60.  3.100
  libavdevice    60.  1.100 / 60.  1.100
  libavfilter     9.  3.100 /  9.  3.100
  libswscale      7.  1.100 /  7.  1.100
  libswresample   4. 10.100 /  4. 10.100
  libpostproc    57.  1.100 / 57.  1.100

[wav @ 0000023cb642ebc0] Estimating duration from bitrate, this may be inaccurate
[wav @ 0000023cb642ebc0] Could not find codec parameters for stream 0 (Audio: none ([255][255][0][0] / 0xFFFF), 48000 Hz, 
1 channels, 103 kb/s): unknown codec
Consider increasing the value for the 'analyzeduration' (0) and 'probesize' (5000000) options
Input #0, wav, from 'C:\Development\modding-cyberpunk\4ddicted\archive\source\archive\base\localization\common\vo\civ_mid_m_85_mex_30_mt_vista_del_rey_f_1ed3f72f92559000.wem':
  Duration: 00:00:05.94, bitrate: 103 kb/s
  Stream #0:0: Audio: none ([255][255][0][0] / 0xFFFF), 48000 Hz, 1 channels, 103 kb/s
Unsupported codec with id 0 for input stream 0
[FORMAT]
filename=C:\Development\modding-cyberpunk\4ddicted\archive\source\archive\base\localization\common\vo\civ_mid_m_85_mex_30_mt_vista_del_rey_f_1ed3f72f92559000.wem
nb_streams=1
nb_programs=0
format_name=wav
format_long_name=WAV / WAVE (Waveform Audio)
start_time=N/A
duration=5.937938
size=76925
bit_rate=103638
probe_score=99
[/FORMAT]

Validation

What is worth mentioning is that Audioware will actually validate many properties of your audios on game startup, here's a non-exhaustive list.

Guarantees

The reason behind these numerous validation checks: it then allows Audioware to make assumptions about your sounds bank.

Sections

Manifest can contain any of the following sections.

Sections provide "good defaults", a way to classify your audio assets, and even more.

SFX

sfx is used to define simple sounds.

my_custom_sfx: ./somewhere/sfx.ogg

Onos

onos (onomatopeia) is used to define audio with 2 files each, one per gender.

my_custom_ono:
    fem: ./somewhere/ono.wav
    male: ./somewhere/else/ono.wav

Voices

voices (sometimes called voiceovers) is used to define audio with multiple files each
and optional subtitles.

Simple Voice

my_simple_voice:
  en-us: ./some/voice.wav

Simple Voice with subtitle

my_simple_voice:
  en-us:
    file: ./some/voice.wav
    subtitle: "hello world"

Plural Voice

version: 1.0.0
voices:
  my_plural_voice:
    en-us:
      fem: ./fem_intro.mp3
      male: ./male_intro.mp3
      subtitle: "Let me introduce myself, I'm V."
  my_other_plural_voice:
    en-us:
      fem:
        file: ./fem_wake_up.mp3
        subtitle: "Looks yourself in the mirror, girl."
      male:
        file: ./male_wake_up.mp3
        subtitle: "Look yourself in the mirror, dude."

Music

music defines songs and ambience music.

version: 1.0.0
music:
  gorillaz_feel_good_inc: ./feel-good-inc.mp3

Settings

Any sound will accept the following settings.

🗃️ Usage

This allows to specify how audio will be handled in memory.

my_custom_audio:
  file: ./somewhere/audio.wav
  usage: on-demand

Each section already has its own default usage when left unspecified, see Sections.

You can choose between possible values: on-demand, in-memory and streaming.

in-memory

The audio is loaded all-at-once in-memory on game startup and kept around for the whole duration of the game session.

on-demand

The audio is loaded all-at-once each time on-demand, and never kept around.

streaming

The audio is streamed on-demand.

🔉 Volume

You can set Volume factor as follow:

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    volume: 2.0 # 2 times louder !
my_other_audio:
  file: ./somewhere/else/audio.ogg
  settings:
    volume: 0.5 # 2 times softer

🕟 Start time

This will play your audio with a delay.

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    start_time: 10s # 10 seconds delay

🔚 Start position

This will play your audio further from start.

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    start_position: 1s # start playing directly at 1s

🍕 Region

This will only play the specified region of audio.

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    region:
      starts: 120ms # starts directly from 1.2s
      ends: 8s # ends at 8s

🔁 Loop

This will loop audio until explicitly stopped.

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    loop: true

⏩ Playback rate

This will play your audio faster, or slower.

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    playback_rate: x0.5 # plays twice as slow

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    playback_rate: x2 # plays twice as fast

You can also specify the value in semitones as follow.

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    playback_rate: 2♯ # adjusts by 2 semitones

↔️ Panning

This adjust from where the audio originates from, from left to right.

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    panning: 0.0 # plays fully on left side

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    panning: 1.0 # plays fully on right side

⤴️ Fade-in tween

This will play your audio gradually fading-in.

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    fade_in_tween:
      start_time: 1s # starts playing directly from 1s
      duration: 3s # fade-in duration
      Linear: # linear fade-in curve (no value needed)

my_custom_audio:
  file: ./somewhere/audio.wav
  settings:
    fade_in_tween:
      start_time: 1s # starts playing directly from 1s
      duration: 3s # fade-in duration
      InPowi: 3 # easing-in with power 3

Possible values for easing can be found here.

Routing

Each section in the manifest will be routed to different tracks internally.

This is important because each track will come with different behavior.

Volume settings

Depending on which section audio is defined, it will be affected by a specific game volume setting.

Parameters

Likewise each track will be affected, or not, by preset and reverb mix.

Going further

This might sounds restrictive at first, but it's actually a way to provide good defaults while being easily worked-around when needed.

API

Audioware's API integrates seamlessly with Cyberpunk AudioSystem, but it offers more.

To start using it right away, continue to the Developper Guide.

If you need a deeper understanding on how it's built, Internal docs are available.

Developer guide

The simplest way to get going uses Cyberpunk 2077's native game system called AudioSystem, as you normally would with vanilla¹ sounds.

When you start requiring a little bit more control, or want to add-in some audio effects, it's usually time to reach for AudioSystemExt and AudioSettingsExt.

And you can also modify Global Parameters at anytime during the game session.

Last but not least, your sounds can be played on audio emitter(s) thanks to Spatialization.

AudioSystem

Once defined, each audio ID is automatically registered on startup, making it available for scripting in-game.

If you simply want to play any custom sound, you can use AudioSystem as you normally would for vanilla sounds.

GameInstance.GetAudioSystem(game).Play(n"my_custom_audio");

It also accepts any of the usual parameters that AudioSystem's methods support.

Currently all these methods are supported:

• Play
• Stop
• Switch
• PlayOnEmitter
• Parameter: see Parameters

AudioSystemExt

AudioSystemExt is an enhanced system over Cyberpunk's AudioSystem.

This system exposes both the exact same API as its counterpart, but also similar methods with additional parameters.

For example, if you want your audio to fade-in linearly during 5secs:

import Audioware.LinearTween

//                                      ⬇️ notice 'Ext' extension here
let system = GameInstance.GetAudioSystemExt(game);
let v = GetPlayer(game).GetEntityID();

// play audio                            ⬇️ with 5s linear fade-in
system.Play(n"my_custom_audio", v, n"V", LinearTween.Immediate(5.));

// later on, stop audio                  ⬇️ with 2s linear fade-out
system.Stop(n"my_custom_audio", v, n"V", LinearTween.Immediate(2.));

Going further

Combined with Codeware, you can e.g. quickly create atmosphere like so:

let weather = GameInstance.GetWeatherSystem(game);
weather.SetWeather(n"24h_weather_rain", 20.0, 9u);
GameInstance.GetAudioSystemExt(game).Play(n"milles_feuilles");

AudioSettingsExt

Earlier we saw that settings can be defined in manifest, but these settings can also be specified in scripts:

// builder is a mutable ref
let builder: ref<AudioSettingsExtBuilder> = AudioSettingsExtBuilder.Create();
// it supports the same settings as definable in manifest, except start_position
builder.SetFadeInTween(ElasticTween.ImmediateIn(5.0, 0.25));
builder.SetPanning(0.3);
builder.SetPlaybackRate(1.1);
builder.SetVolume(0.9);
// once built it returns an immutable ref with different type
let settings: ref<AudioSettingsExt> = builder.Build();

GameInstance
.GetAudioSystemExt(game)
.Play(n"still_dre", GetPlayer(game).GetEntityID(), n"V", scnDialogLineType.Regular, settings);

GameInstance
    .GetAudioSystemExt(game)
    .Play(
        n"still_dre",
        GetPlayer(game).GetEntityID(),
        n"V",
        scnDialogLineType.Regular, 
        AudioSettingsExtBuilder.Create()
            .WithFadeInTween(ElasticTween.ImmediateIn(5.0, 0.25))
            .WithPanning(0.3)
            .WithPlaybackRate(1.1)
            .WithVolume(0.9)
            .Build()
    );

Parameters

Audioware exposes the following parameters.

Reverb Mix

Allows to alter reverb like e.g. when in a cavern.

let value: Float; // reverb can be between 0.0 and 1.0 (inclusive)
GameInstance.GetBlackboardSystem(game)
    .Get(GetAllBlackboardDefs().Audioware_Settings)
    .SetFloat(GetAllBlackboardDefs().Audioware_Settings.ReverbMix, value, true);

Preset

Allows to alter frequencies like e.g. underwater or on the phone.

You can also set it manually, if needed:

let value: Preset; // possible values: None, Underwater, OnThePhone
GameInstance.GetBlackboardSystem(game)
    .Get(GetAllBlackboardDefs().Audioware_Settings)
    .SetInt(GetAllBlackboardDefs().Audioware_Settings.AudioPreset, value, true);

Spatialization

Thanks to kira Audioware supports audio spatialization, which means audio that moves along its emitter, getting louder when closer and softer when further, along with left-right panning.

Registration

Audio emitter(s) must be registered before you can emit audio from them, but they are automatically cleaned up whenever emitter despawns or dies.

if !GameInstance.GetAudioSystemExt(game).IsRegisteredEmitter(emitterID) {
    GameInstance.GetAudioSystemExt(game).RegisterEmitter(emitterID);
}

/// for Humans
@wrapMethod(NPCDeathListener)
protected cb func OnStatPoolCustomLimitReached(value: Float) -> Bool {
    let wasAlive = !this.npc.m_wasJustKilledOrDefeated;
    let out = wrappedMethod(value);
    if wasAlive && this.npc.m_wasJustKilledOrDefeated {
        let id = this.npc.GetEntityID();
        let name = this.npc.GetDisplayName(); // or whatever you named it
        // fades for 2sec, with intensity 0.2
        let fadeOut = LinearTween.ImmediateOut(2.0, 0.2);

        GameInstance
            .GetAudioSystemExt(this.npc.GetGame())
            .Stop(n"my_custom_audio", id, name, fadeOut);
    }
    return out;
}
/// for Robots
@wrapMethod(NPCDeathListener)
protected cb func OnStatPoolMinValueReached(value: Float) -> Bool { ... }

Usage

Then, simply use the OnEmitter variants of the methods:

// ⚠️ emitterID and emitterCName must be both valid and non-default
GameInstance.GetAudioSystemExt(game).PlayOnEmitter(n"my_custom_audio", emitterID, emitterCName);

// if should stop at some point...
GameInstance.GetAudioSystemExt(game).StopOnEmitter(n"my_custom_audio", emitterID, emitterCName);

Auto-registration

Whenever you want to turn all particular entities of a kind into audio emitters automatically, you can reach out for Codeware game events.

Here's a dummy example on how to use F1 to register any audio emitter in crosshair.

import Audioware.*

public class AutoEmittersSystem extends ScriptableSystem {
    private func OnAttach() {
        GameInstance.GetCallbackSystem().RegisterCallback(n"Input/Key", this, n"OnKeyInput")
        // listen to F1 being pressed or released
        .AddTarget(InputTarget.Key(EInputKey.IK_F1));
    }
    private cb func OnKeyInput(evt: ref<KeyInputEvent>) {
        // when F1 is released
        if NotEquals(evt.GetAction(), EInputAction.IACT_Release) { return; }
        // some songs defined in manifest
        let sounds = [ 
            n"my_custom_song_01",
            n"my_custom_song_02", 
            n"my_custom_song_03",
            n"my_custom_song_04", 
            n"my_custom_song_05"
        ];
        // get a random sound above
        let eventName = sounds[RandRange(0, ArraySize(sounds) -1)];
        // prepare some settings
        let tween = new LinearTween();
        tween.startTime = RandRangeF(1.0, 3.0);
        tween.duration = RandRangeF(3.0, 4.5);
        let emitterID: EntityID;
        let emitterCName: CName = n"DummyTest";

        let game = this.GetGameInstance();
        // get entity V currently looks at (crosshair)
        let target = GameInstance.GetTargetingSystem(game).GetLookAtObject(GetPlayer(game));
        if !IsDefined(target) { return; }
        emitterID = target.GetEntityID();
        if !GameInstance.GetAudioSystemExt(game).IsRegisteredEmitter(emitterID) {
            GameInstance.GetAudioSystemExt(game).RegisterEmitter(emitterID);
        }
        GameInstance.GetAudioSystemExt(game).PlayOnEmitter(eventName, emitterID, emitterCName);
    }
}

Docs

The traditional Rust docs can be found here🦀, but they are still being written and rather incomplete at the moment.

It merely contains implementation details, so if you're more interested in using Audioware right away please head back to the Developer Guide.

Integration

How well engine matches our expectations when it comes to integrate seamlessly with Cyberpunk 2077.

Let's review what you get for free.

🔉 Game volume settings

We've already seen that custom audio are affected by player's game volume settings.

⏯️ Dynamic pause/resume when in menus

All audios will be properly paused when entering any menu,
and resumed when back in-game.

🏊‍♂️ Dynamic underwater preset

As previously stated, audio will dynamically have its frequencies adjusted by Underwater preset whenever V enter or exit water, for the tracks where it makes sense.

This is currently not implemented for cars.

🧹 Clean game sessions

Spatial scene along with its emitters, every track and currently playing sounds will be completely stopped and reset on every save load.

You don't need to worry about memory leaks.