ndspy.soundSequenceArchive: Sound Sequence Archives

The ndspy.soundSequenceArchive module lets you work with SSAR sound sequence archive files. These are generally used for sound effects.

See also

If you aren’t familiar with how SDAT files are structured, consider reading the appendix explaining this.

ndspy.soundSequence – contains sequence event classes, and some detailed explanations of how to use them.

class ndspy.soundSequenceArchive.SSAR([file[, unk02[, names]]])

A SSAR sequence archive file. This contains a blob of sequence events data, and a list of “sequences” that are essentially just pointers to starting locations in that data.

Parameters:

  • file (bytes) – The data to be read as an SSAR file. If this is not provided, the SSAR object will initially be empty.

  • unk02 – The initial value for the unk02 attribute.

  • names (list of str) –

    A list of names for the sequences in the SSAR. SSAR files do not themselves contain names for their sequences, but sequence names may be present elsewhere in an SDAT file; hence this parameter.

    This will be ignored if file is not provided. Any sequences that do not have names provided here will be given placeholder names.

    default:

    []

dataMergeOptimizationID

When saving a SDAT file containing multiple SSAR files, ndspy will check if any of them save to identical data. If it finds any, it will only encode the data for them once and then reference it multiple times, to save some space. This attribute is an extra field that is also compared between SSAR files, which you can use to exclude particular ones from this optimization.

Since this defaults to 0 for all SSARs created from scratch, this optimization will happen by default. It’s unlikely that you will need to use this attribute to disable the optimization, but you can.

Note

This value is not explicitly saved in the SSAR file or in the SDAT file containing it.

Type:

int

Default:

0

events

The list of sequence events contained in this SSAR, shared by all sequences. This is only available in parsed SSARs (ones with parsed set to True).

See also

Parsed and Unparsed SSEQs and SSARs – the introductory text explaining the difference between parsed and unparsed SSARs.

eventsData – the equivalent attribute that is available before parsing.

Type:

list of ndspy.soundSequence.SequenceEvent

Default:

[]

eventsData

The raw event data contained in this SSAR, shared by all sequences. This is only available in unparsed SSARs (ones with parsed set to False).

See also

Parsed and Unparsed SSEQs and SSARs – the introductory text explaining the difference between parsed and unparsed SSARs.

events – the equivalent attribute that becomes available after parsing.

Type:

bytes

parsed

Whether parse() has ever been called on this SSAR object. This determines whether eventsData or events is available.

This attribute is read-only.

See also

Parsed and Unparsed SSEQs and SSARs – the introductory text explaining the difference between parsed and unparsed SSARs.

Type:

bool

Default:

True

sequences

The sequences in this SSAR, in the form of a list of name-value pairs containing ndspy.soundSequence.SSARSequence instances. The sequences all share the same pool of events (eventsData, events), and only differ in their starting positions and some metadata.

This is presented as a list of name-value pairs because collections.OrderedDict – the best choice for an order-preserving dictionary type – does not provide an easy way to adjust the order of its elements.

See also

ndspy.indexInNamedList(), ndspy.findInNamedList(), ndspy.setInNamedList() – helper functions you can use to find and replace values in this list.

Type:

list of (name, sequence), where name is of type str or None, and sequence is of type SSARSequence or None

Default:

[]

unk02

The value following the SSAR’s file ID in the “INFO” section of the SDAT file it is contained in. Its purpose is unknown.

Note

This value is not explicitly saved in the SSAR file, but it is saved in the SDAT file if the SSEQ is within one.

Type:

int

Default:

0

classmethod fromEventsAndSequences(events, sequences[, unk02])

Create a new SSAR object from a list of sequence events and a list of sequences.

Parameters:
classmethod fromFile(filePath[, ...])

Load an SSAR from a filesystem file. This is a convenience function.

Parameters:

filePath (str or other path-like object) – The path to the SSAR file to open.

Further parameters are the same as those of the default constructor.

Returns:

The SSAR object.

Return type:

SSAR

parse()

Attempt to process eventsData to create events. If successful, this switches the SSAR from the unparsed to the parsed state (see Parsed and Unparsed SSEQs and SSARs for a more detailed explanation).

Parsing events data is complex and even completely impossible in some cases. If unsuccessful, this function will raise an exception and the SSAR will remain in the unparsed state.

This function is idempotent, meaning that calling it on a SSAR already in the parsed state will do nothing.

save()

Generate file data representing this SSAR, and then return that data, unk02, and a list of sequence names as a triple. This matches the parameters of the default class constructor.

Returns:

The SSAR file data, unk02, and a list of sequence names.

Return type:

(data, unk02, names), where data is of type bytes, unk02 is of type int, and names is a list of str

saveToFile(filePath)

Generate file data representing this SSAR, and save it to a filesystem file. This is a convenience function.

Parameters:

filePath (str or other path-like object) – The path to the SSAR file to save to.

class ndspy.soundSequenceArchive.SSARSequence(firstEvent_firstEventOffset, [bankID, [volume, [channelPressure, [polyphonicPressure, [playerID, ]]]]]*[, parsed=True])

A sequence within a SSAR sequence archive file. These generally contain sound effects.

When created using the default constructor, the sequence will be put into the parsed state.

See also

Parsed and Unparsed SSEQs and SSARs – the introductory text explaining the difference between parsed and unparsed SSARs.

Parameters:

  • firstEvent_firstEventOffset (int or None (if parsed is False), or ndspy.soundSequence.SequenceEvent or None (if parsed is True)) –

    The sequence event – or offset thereof – where the sequence player should begin playing when it plays this sequence.

    If parsed is False, this will be the initial value for the firstEventOffset attribute.

    If parsed is True, this will be the initial value for the firstEvent attribute.

    In either case, None indicates that the sequence has no event data at all; such a sequence will do nothing when played.

  • bankID – The initial value for the bankID attribute.

  • volume – The initial value for the volume attribute.

  • channelPressure – The initial value for the channelPressure attribute.

  • polyphonicPressure – The initial value for the polyphonicPressure attribute.

  • playerID – The initial value for the playerID attribute.

  • parsed –

    The initial value for the parsed attribute.

    default:

    True

bankID

The ID of the instrument bank (SBNK) that this sequence will use.

Type:

int

Default:

0

channelPressure

The channel pressure for the sequence. The exact meaning of this is unclear.

Type:

int

Default:

64

firstEvent

A reference to this sequence’s first event in its parent SSAR’s events list (SSAR.events). This is only available in parsed SSAR sequences (ones with parsed set to True).

A value of None indicates that the sequence has no event data at all.

Warning

This event must appear somewhere in the parent SSAR’s events list (SSAR.events), or else you’ll experience errors that prevent you from saving your SSAR!

See also

Parsed and Unparsed SSEQs and SSARs – the introductory text explaining the difference between parsed and unparsed SSARs.

firstEventOffset – the equivalent attribute that is available before parsing.

Type:

ndspy.soundSequence.SequenceEvent or None

firstEventOffset

The offset at which this sequence’s first event is located in its parent SSAR’s raw event data (SSAR.eventsData). This is only available in unparsed SSAR sequences (ones with parsed set to False).

A value of None (or -1) indicates that the sequence has no event data at all.

See also

Parsed and Unparsed SSEQs and SSARs – the introductory text explaining the difference between parsed and unparsed SSARs.

firstEvent – the equivalent attribute that becomes available after parsing.

Type:

int or None

parsed

Whether parse() has ever been called on this sequence’s parent SSAR object. This determines whether firstEventOffset or firstEvent is available.

Unless you’re doing something like manually moving a sequence from an unparsed SSAR to a parsed one, it’d be a good idea to treat this as a read-only attribute.

See also

Parsed and Unparsed SSEQs and SSARs – the introductory text explaining the difference between parsed and unparsed SSARs.

Type:

bool

playerID

The ID of the sequence player that will be used to play this sequence.

Type:

int

Default:

0

polyphonicPressure

The polyphonic pressure for the sequence. The exact meaning of this is unclear.

Type:

int

Default:

50

volume

The overall volume of the sequence. This is an integer between 0 and 127, inclusive.

Type:

int

Default:

127

save()

Return this SSAR sequence’s first event or first event offset, bankID, volume, channelPressure, polyphonicPressure, and playerID as a 6-tuple. This matches the parameters of the default class constructor.

Returns:

The first event (if parsed is True) or first event offset (if parsed is False), bankID, volume, channelPressure, polyphonicPressure, and playerID.

Return type:

(firstEvent_firstEventOffset, bankID, volume, channelPressure, polyphonicPressure, playerID), where firstEvent_firstEventOffset is of type (int if parsed is False, or ndspy.soundSequence.SequenceEvent if parsed is True) or None, and all of the other elements are of type int