srctools.sndscape

The sndscape module reads and writes soundscape files. Basic usage involves first parsing the file into a Keyvalues tree, then parsing into soundscapes:

with open('soundscape.txt', 'r') as f:
        kv = Keyvalues.parse(f)
soundscapes = Soundscape.parse(kv)

The opposite is done by simply calling Soundscape.export() on each soundscape to append to a file.

Enumerations

class srctools.sndscape.PosType

Bases: Enum

Type of sound position.

RANDOM = 'random': Play from a random position near the player

AMBIENT = 'ambient': Default behaviour, play at full volume regardless of location.

Classes

class srctools.sndscape.Soundscape( *, name: str, rand_sounds: list[RandSound] = ..., loop_sounds: list[LoopSound] = ..., children: list[SubScape] = ..., dsp: int | None = None, dsp_spatial: int | None = None, dsp_volume: float = 1.0, fadetime: float = 0.0, soundmixer: str | None = None, )

A single soundscape definition.

name: str: The name of the soundscape with its original casing.

rand_sounds: list[RandSound]: All playrandom rules defined by this soundscape.

loop_sounds: list[LoopSound]: All playloooping rules defined by this soundscape.

children: list[SubScape]: All playsoundscape rules defined by this soundscape.

dsp: int | None: Sets the DSP preset while this soundscape is active.

dsp_spatial: int | None: Sets the spatial DSP preset while this soundscape is active.

dsp_volume: float: Controls the volume of all DSP effects.

fadetime: float: If non-zero, overrides the duration of the crossfade between this and the previous soundscape.

soundmixer: str | None: Makes a specific soundmixer active, to override sound priority.

classmethod parse( file: Keyvalues, ) → dict[str, Soundscape]

Parse all soundscape definitions in a file.

This returns a dict mapping casefolded names to Soundscapes.

classmethod parse_one(kv: Keyvalues) → Soundscape: Parse a single soundscape definition.

export(file: FileWText) → None

Write a soundscape to a file.

Pass a file-like object open for text writing.

class srctools.sndscape.SubScape( *, name: str, volume: tuple[float | Volume, float | Volume] = (srctools.sndscript.VOL_NORM, srctools.sndscript.VOL_NORM), pos_offset: int = 0, pos_override: int | None = None, ambient_pos_override: int | None = None, )

A sub-soundscape entry, which triggers another soundscape to play also.

name: str: The name of the soundscape to play

volume: tuple[float | Volume, float | Volume]: Modulates the volume of the child soundscape, and anything it plays.

pos_offset: int

pos_override: int | None: If set, overrides all positions to use this entity index.

ambient_pos_override: int | None: If set, overrides non-positioned sounds to instead to use this position.

classmethod parse(kv: Keyvalues) → SubScape: Parse a playsoundscape entry.

export(file: FileWText) → None: Write this block to a file.

abstract class srctools.sndscape.SoundRule

These attributes are common to RandSound and LoopSound.

position: PosType | int | Vec

The position to play the sound from. This can take a few forms:

PosType.AMBIENT (default): Plays at full volume regardless of location.
PosType.RANDOM: Plays from a random position near the player.
An integer: This is the index of an entity referenced by the env_soundscape.
A vector: This is a fixed position in world, only useful for map-specific soundscapes.

volume: tuple[float | Volume, float | Volume]: Modulates the volume of the sound.

pitch: tuple[float | Pitch, float | Pitch]: Alters the pitch of the sound when played.

level: tuple[int | Level, int | Level]: Adjusts how far and quickly the sound fades with distance.

no_restore: bool: If true, this rule is discarded if reloading from a save.

class srctools.sndscape.RandSound( *, position: PosType | int | Vec = PosType.AMBIENT, volume: tuple[float | Volume, float | Volume] = (srctools.sndscript.VOL_NORM, srctools.sndscript.VOL_NORM), pitch: tuple[float | Pitch, float | Pitch] = (Pitch.PITCH_NORM, Pitch.PITCH_NORM), level: tuple[int | Level, int | Level] = (Level.SNDLVL_NORM, Level.SNDLVL_NORM), no_restore: bool = False, time: tuple[float, float], sounds: list[str], )

Bases: SoundRule

A playrandom entry in a soundscape. These are played at random intervals.

time: tuple[float, float]: The time to wait between each play of this sound.

sounds: list[str]: The filenames to randomly pick from when playing.

classmethod parse(kv: Keyvalues) → RandSound: Parse a playrandom entry.

export(file: FileWText) → None: Write this block to a file.

class srctools.sndscape.LoopSound( *, position: PosType | int | Vec = PosType.AMBIENT, volume: tuple[float | Volume, float | Volume] = (srctools.sndscript.VOL_NORM, srctools.sndscript.VOL_NORM), pitch: tuple[float | Pitch, float | Pitch] = (Pitch.PITCH_NORM, Pitch.PITCH_NORM), level: tuple[int | Level, int | Level] = (Level.SNDLVL_NORM, Level.SNDLVL_NORM), no_restore: bool = False, radius: float = 1.0, sound: str, )

Bases: SoundRule

A playlooping entry in a soundscape.

radius: float: Overrides the maximum audible distance for the sound.

sound: str: The looping sound to play.

classmethod parse(kv: Keyvalues) → LoopSound: Parse a playlooping entry.

export(file: FileWText) → None: Write this block to a file.