API

Package

pyawe_awb

AWB File Reader and Parser

Installation

(venv) pip install pyawe_awb

Description

The Python package provides a parser for the AWE Designer's AWB target file. The package also contains the binary structure definitions of the AWE binary protocol on the socket to and from AWE Server.

Usage

AweFile

The AweFile class reads the AWB file and provides the designs layout information.

from pyawe_awb.awb import AwbFile

awb = AwbFile.from_file("myfile.awb")
print(f"Layout requires #in channels: {awb.layout_info.nr_input_channels}")

For more information read the documentation.

Modules

pyawe_awb.awb

Module for parsing and handling AWB files

pyawe_awb.awb.AwbFile

Loads ab AWB file and provides methods to query its content

class_id_counts property

Returns a dictionary with the information how many times a class ID has occurred.

The dictionary's key is a class ID value (int) and it holds a sub-dictionary with the keys

• cnt: number of times this module class is instantiated/used
• name: name of module class, like "ModuleAGCLimiterCoreV2", or "unknown"

See

class_ids property returns only a list of class IDs used.

Returns:

Type	Description
dict[int, dict[str, Any]]	A dictionary mapping class IDs to number of occurrences of that specific class ID. The sum of all class ID occurrences is the number of modules in the signal flow.

class_ids property

Obtains a list of AWE module class IDs used in this design. If more "statistic" information is relevant, the property class_id_counts can be used.

Returns:

Type	Description
list[int]	A sorted list of class IDs.

core_ids property

Lists all core/instance IDs

Returns:

Type	Description
list[int]	list of unique coreID values of this AWB

layout_info property

Parses the internal data structure and uses the appropriate create_wire commands to derive the required layout information, like sample rates, fundamental block size and number of input and output channels.

Raises:

Type	Description
AwbFileNoIOInfo	In case no information about input and output pins were found. This might happen in AWB data used for tuning purposes.

Returns: an IOPinInfo structure

nr_commands property

Returns:

Type	Description
int	number of commands in the AWB file

nr_instances property

This property supports the multi-instance feature of AWE Core; It can be used to obtain the number of instances encoded into the AWE design.

Returns:

Type	Description
int	Number of instances in the AWB file.

unparsed_cmds property

returns commands for which the payload could not be parsed correctly

__init__(data)

Constructs the AwbFile object with a given set of AWB commands.

Parameters:

Name	Type	Description	Default
data	ListContainer	a list of AWB commands	required

build()

Builds the grammar of the AwbFile instance data into raw bytes.

Returns:

Type	Description
bytes	bytes buffer for the grammar of the AwbFile instance

cmd_at_pos(pos)

Returns the container information at a certain (word) position in the file, typically this position is returned from AWE Core load when something goes wrong.

Additionally, a command index is returned. The index of the command (0 based), can be used to derive the line number in the AWS file.

Parameters:

Name	Type	Description	Default
pos	int	index into the file (4 byte word based)	required

Returns:

Type	Description
tuple[Container, int]	tuple of Container object and command index

Raises:

Type	Description
AwbFileError	if position is larger than file/AWB content

diff(other)

Parameters:

Name	Type	Description	Default
other	AwbFile	AwbFile	required

Returns:

Type	Description
AwbFile	AwbFile structure

flatten()

This method flattens the current AWB data containing PFID_BundlePackets commands.

Any AWB data not inside a bundle will be copied; this mainly applies to special commands, like STOP and DESTROY and START.

Returns:

Type	Description
AwbFile	New AwbFile instance with a flattened version of the current AWB data.

from_buffer(buffer) classmethod

Constructs the AwbFile object from a (bytes) buffer.

Parameters:

Name	Type	Description	Default
buffer	bytes	bytes buffer containing raw AWB data	required

Raises:

Type	Description
StreamError	in case the buffer could not be parsed

from_file(awb_path) classmethod

Constructs the AwbFile object. It loads the AWB file into the class.

Parameters:

Name	Type	Description	Default
awb_path	str | Path	path to the AWB file	required

Raises:

Type	Description
FileNotFoundError	if file was not found
StreamError	in case the file could not be parsed

from_stream(stream) classmethod

Constructs the AwbFile object from a stream object (files, pipes, sockets, and other streaming sources).

Parameters:

Name	Type	Description	Default
stream	IO	Python stream object	required

Raises:

Type	Description
StreamError	in case the stream could not be parsed

order_by_core_id_list(core_ids, add_audiostart=True, ignore_missing=True)

function to split an AWB according to a provided list of core IDs.

The core ID list consists of a list of lists. Each of these inner lists may contain a list of integer core ID values which must match the core ID value inside the AWB to be split.

When an item contains multiple core ID values, the original's AWB command data for these core IDs is combined into one single AWB container.

Typically, this core ID list is ordered in a way that all IDs for early audio AWE instances are the first entries in the 'core_ids' list and the last entry contains all core ID values of the late boot AWE instances. Example for a QC target: [[DSP0-coreID], [DSP1-coreID], [DSP2-coreID, ARM-coreID]]

Parameters:

Name	Type	Description	Default
core_ids	list[list[int]]	list of core IDs, in form of [[id0], [id1], [id2, id3]]	required
add_audiostart	bool	if True an AWB audio_pump command is added as last command to each command group	True
ignore_missing	bool	if True there will be a None item inserted into the output list when a core ID cannot be found in the AWB.	True

Returns:

Type	Description
list[AwbFile]	A list of AwbFile objects; this list will have the same length as the input core_ids, but
list[AwbFile]	may contain None values, depending on whether ignore_missing was set to True.

set_core_id(abs_or_delta_value, is_delta=False)

Updates the core ID fields in all containers with a new value.

Parameters:

Name	Type	Description	Default
abs_or_delta_value	int	may either be an absolute value, or an offset	required
is_delta	bool	defines how abs_or_delta_value is to be interpreted	False

Returns:

Type	Description
list[int]	The list of new core ID values of the file. Example: when coreID was 16 and
list[int]	abs_or_delta_value was 4 and is_delta was True, then [12] is returned.

Raises:

Type	Description
AwbFileError	when not-allowed values have been applied.

split(secondary_destroy=False, secondary_audiostart=False)

Splits the AWB into a structure containing dedicated AwbFile objects per coreId.

Parameters:

Name	Type	Description	Default
secondary_destroy	bool	if True an AWB destroy command is prefixed	False
secondary_audiostart	bool	if True an AWB audio_pump command is added as last command	False

Returns: dictionary of AwbFile objects with coreId being the key

store(fpath)

stores the data in another AWB file

verify_against(class_IDs)

Checks which of the class IDs in the signal flow are not available in a list of given class IDs.

Typically, the class_IDS parameter's value is the list of AWE modules available in the software (BSP). Hence, this method can be used to check if loading of the signal flow into an AWE Core instance will fail or not; in other words: if a given AWB signal flow is supported by the system.

The AWB signal flow is incompatible when the returned list is not empty.

Parameters:

Name	Type	Description	Default
class_IDs	list[int]	list of class IDs to verify against.	required

Returns:

Type	Description
list[int]	List of class ID values missing in the class_IDs parameter.

pyawe_awb.awb.AwbFileError

Bases: Exception

Raised when there is a generic error.

pyawe_awb.awb.AwbFileNoIOInfo

Bases: Exception

Raised when no IO information can be found. This might not even be an error. There is no input and output PIN configuration stored in AWB data used for e.g. tuning.

pyawe_awb.layoutinfo

Module contains the container for an AWE layout information

pyawe_awb.layoutinfo.IOPinInfo dataclass

Container with information of the signal flow's input and output pins.

It specifies how the signal flow needs to be integrated, in terms of number of input and output channels, sample rate and fundamental block size.

Attributes:

Name	Type	Description
nr_input_channels	int	number of input channels the design requests
nr_output_channels	int	number of output channels
fundamental_blocksize	int	processing blocksize in number of samples
input_sample_rate	float	expected audio sample rate on the input pin
output_sample_rate	float	sampling rate of audio content at the output pin. Note: While technically AWE Core does allow to use different input and output sample rates, it also requires the use the same fundamental block size on these pins. As this makes no real sense in terms of signal processing use-cases, the value of input_sample_rate and output_sample_rate are the same almost all time.