pywwise 0.2.4

A comprehensive Wwise Authoring API wrapper - fully documented, with auto-completion in mind.

PyWwise

PyWwise is an open-source Python wrapper around the Wwise Authoring Application Programming Interface (WAAPI). PyWwise is meant to make Wwise scripting (e.g. automation, data validation, etc.) much easier to achieve. There are multiple benefits in using PyWwise; the three main highlights are:

• Pythonic Architecture
• Object-Oriented
• Fully Documented

Installation

PyWwise is available on the Python Package Index, and so it is recommended to install it via pip. Using CMD, Terminal, PowerShell, or any command-line interface of your choice, run the command pip install pywwise to install the latest version of PyWwise.

PyWwise is intended to be used with Wwise versions 2021 and above.

Usage

Getting started with PyWwise is easy: the first step is always to import pywwise and initialize a WAAPI connection to an instance of Wwise using the factory function new_waapi_connection. PyWwise is fully documented, so each function or topic will let you know what will be needed. Using an IDE like JetBrains PyCharm Community is recommended.

Since PyWwise is based on WAAPI and the waapi-client package, you may also use the official Wwise Authoring API Reference, which is maintained by Audiokinetic. Their documentation provides a complete list of functions and topics which are all supported and reflected by PyWwise.

Modules

The root module pywwise is where the factory function new_waapi_connection exists; this functions establishes a connection with an instance of Wwise. When working with a single connection, the PyWwise convention is to name the connection "ak". Here is a simple example:

import pywwise

ak = pywwise.new_waapi_connection()  # the default URL is "ws://127.0.0.1:8080/waapi"
path = pywwise.SystemPath("C:/Users/leozin/Documents/WwiseTests/TestTone.wav")  # SystemPath is an alias of pathlib.Path
ak.wwise.debug.generate_tone_wav(path)  # this will output a WAV file containing a tone!
ak.disconnect()

Alternatively, you may use a with statement for context management, so the connection to Wwise is automatically closed once the with block is done. Here is a variation on the previous example:

from pywwise import new_waapi_connection, SystemPath

with new_waapi_connection() as ak:  # the default URL is "ws://127.0.0.1:8080/waapi"
    path = SystemPath("C:/Users/leozin/Documents/WwiseTests/TestTone.wav")  # SystemPath is an alias of pathlib.Path
    ak.wwise.debug.generate_tone_wav(path)  # this will output a WAV file containing a tone!

Inside the root module pywwise, you will find any PyWwise core type, enum, etc. meant for end-users. It is also possible to import those directly from PyWwise's submodules, but that is not necessary.

Examples

The examples below are a brief introduction on using PyWwise. For more information, refer to the wiki on the GitHub repo.

Getting the active State from the sound engine

As you get familiar with PyWwise, you will notice that many functions use specialized PyWwise types for params/args instead of primitives such as str. This is to maximize readability, allow type-matched behaviours, and deploy some error checking (e.g. the constructor in GUID checks to see if the provided value is a valid GUID, in terms of format). Here is an example showcasing GUID:

from pywwise import new_waapi_connection, GUID

with new_waapi_connection() as ak:  # the default URL is "ws://127.0.0.1:8080/waapi"
    wwise_obj_guid = GUID("{3182E70A-1CD2-4ABD-8652-EEA2E600E4A7}")  # if the GUID is invalid, a ValueError is thrown
    active_state: tuple[str, str] = ak.soundengine.get_state(wwise_obj_guid)  # the type hint is for readability only
    print(active_state)

Other common primitive-like types are Name, ShortID, ProjectPath, PlayingID, and GameObjectID. Some of those have member functions to check validity or get common "default" values.

Generating a tone WAV

PyWwise has many enumerations that help WAAPI users obey certain constraints of Wwise (e.g. "quantized" parameters; in other words, parameters that only accept certain values). Here is an example showcasing EBitDepth and ESampleRate:

from pywwise import new_waapi_connection, EBitDepth, ESampleRate, SystemPath

with new_waapi_connection() as ak:  # the default URL is "ws://127.0.0.1:8080/waapi"
    
    output_path = SystemPath("C:/Users/leozin/Documents/WwiseTests/TestTone.wav")
    bit_depth = EBitDepth.INT_16  # Wwise only supports 16-bit integer and 32-bit float; EBitDepth enumerates those options.
    sample_rate = ESampleRate.SR_44100  # Wwise only supports certain sample rates; ESampleRate enumerates all options.
    
    ak.wwise.debug.generate_tone_wav(output_path, bit_depth, sample_rate)

Setting the position of a GameObject in the sound engine

PyWwise also has tons of dataclasses - classes that are primarily containers of data. Good examples are Vector3 (commonly used to represent a point in 3D space) and PlatformInfo (represents a platform entry in Wwise's Platform Manager). Here is example using Vector3:

from pywwise import new_waapi_connection, GameObjectID, Vector3

with new_waapi_connection() as ak:  # the default URL is "ws://127.0.0.1:8080/waapi"
    
    # Position the Transport (Wwise Authoring's default game object) at the world's origin (centre) point.
    ak.soundengine.set_position(GameObjectID.get_transport(), Vector3.get_zero(), Vector3.get_zero())

Setting properties on a Wwise object

PyWwise supports getters and setters for common Wwise object types. To get and set properties on a Wwise object, you will first need to fetch information about the object from Wwise first, before instantiating a WwiseObject (which contains the WwiseProperty members with a getter and setter each):

from pywwise import EObjectType, new_waapi_connection, WaqlQuery, WwiseObjectInfo, Sound

with new_waapi_connection() as ak:  # the default URL is "ws://127.0.0.1:8080/waapi"
    
    # Get object using a WAQL query
    sound_info = ak.wwise.core.object.get(f"$ from type Sound where Name = \"MySound\" take 1")[0]
    sound_obj = Sound(sound_info, ak)  # GUID is cached, but all other properties are "connected" to Wwise.
    
    # Get and set Volume property
    property_name = Sound.volume  # Accessing the property from the class instead of instance returns the property name
    print(f"Current {property_name}: {sound_obj.volume}")  # 0.0
    sound_obj.volume = -6.0  # Will call either ak.wwise.core.object.set_property or ak.wwise.core.object.set_reference
    print(f"New {property_name}: {sound_obj.volume}")  # -6.0