ndspy.soundWave: Sound Waves

The ndspy.soundWave module lets you edit and create SWAV streamed audio files. These are intended to be used for instrument samples, sound effects, and other short sounds.

A SWAV is conceptually similar to a standard WAV audio file. They define a waveform rather than sequence events. SWAVs are limited to only one channel, and shorter loop periods than STRM files.

See also

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

class ndspy.soundWave.SWAV([file])[source]

An SWAV streamed audio file.

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

The raw waveform data. This must be interpreted according to the value of waveType.

Type:bytes
Default:b''
isLooped

Whether the SWAV is looped or just plays through once.

See also

You can use loopOffset to control the beginning of the looped region.

Type:bool
Default:False
loopOffset

The beginning of the looped portion of the SWAV data, measured in words (groups of 4 bytes).

Warning

Due to how totalLength is encoded in the file data, this attribute must not be greater than it, or else you will experience errors upon saving (save())!

See also

In order to loop an SWAV, you also need to set isLooped to True.

Type:int
Default:0
sampleRate

The sample rate the SWAV should be played at.

Type:int
Default:8000
time

A value of unclear meaning. This is pretty much always set to the following:

strm.time = int(16756991 / strm.sampleRate)

Note

This can optionally be recalculated for you automatically upon saving the SWAV. For more information about this, see the documentation for the save() function.

Type:int
Default:0
totalLength

The total length of the SWAV data, measured in words (groups of 4 bytes). This is almost always equal to len(swav.data) // 4, but, for reasons unknown, not always.

Warning

Due to how this is encoded in the file data, this attribute must not be less than loopOffset, or else you will experience errors upon saving (save())!

Note

This can optionally be recalculated for you automatically upon saving the SWAV. For more information about this, see the documentation for the save() function.

Type:int
Default:0
waveType

The format that this SWAV’s waveform data (data) is in.

Type:ndspy.WaveType (or int)
Default:ndspy.WaveType.PCM8
classmethod fromData([data, ]*[, waveType[, isLooped[, sampleRate[, time[, loopOffset[, totalLength]]]]]])[source]

Create an SWAV from raw waveform data.

Parameters:
  • data – The initial value for the data attribute.
  • waveType – The initial value for the waveType attribute.
  • isLooped – The initial value for the isLooped attribute.
  • sampleRate – The initial value for the sampleRate attribute.
  • time – The initial value for the time attribute.
  • loopOffset – The initial value for the loopOffset attribute.
  • totalLength – The initial value for the totalLength attribute.
Returns:

The SWAV object.
Return type:

SWAV
classmethod fromFile(filePath)[source]

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

Parameters:filePath (str or other path-like object) – The path to the SWAV file to open.
Returns:The SWAV object.
Return type:SWAV
save(*[, updateTime=False[, updateTotalLength=False]])[source]

Generate file data representing this SWAV.

Parameters:
  • updateTime (bool) –

    If this is True, time will be updated based on the sample rate, using the formula found in the documentation for the time attribute.

    default:False
  • updateTotalLength (bool) –

    If this is True, totalLength will be updated to be one-fourth the length of data.

    default:False
Returns:

The SWAV file data.
Return type:

bytes
saveToFile(filePath, *[, updateTime=False[, updateTotalLength=False]])[source]

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

Parameters:
  • filePath (str or other path-like object) – The path to the SAV file to save to.
  • updateTime (bool) –

    If this is True, time will be updated based on the sample rate, using the formula found in the documentation for the time attribute.

    default:False
  • updateTotalLength (bool) –

    If this is True, totalLength will be updated to be one-fourth the length of data.

    default:False