srctools.sndscript

Enumerations

Several options have a number of predefined names.

class srctools.sndscript.Pitch

Bases: float, Enum

The constants permitted for sound pitches.

PITCH_NORM = 100.0

PITCH_LOW = 95.0

PITCH_HIGH = 120.0

classmethod parse_interval_kv( kv: Keyvalues, key: str = 'pitch', ) → tuple[float | Pitch, float | Pitch]: Parse an interval of pitches from a subkey of a keyvalues block.

class srctools.sndscript.Channel

Bases: Enum

Different categories of sounds.

DEFAULT = 'CHAN_AUTO'

GUNFIRE = 'CHAN_WEAPON'

VOICE = 'CHAN_VOICE'

TF2_ANNOUNCER = 'CHAN_VOICE2'

ITEMS = 'CHAN_ITEM'

BODY = 'CHAN_BODY'

STREAMING = 'CHAN_STREAM'

CON_CMD = 'CHAN_REPLACE'

BACKGROUND = 'CHAN_STATIC'

PLAYER_VOICE = 'CHAN_VOICE_BASE'

class srctools.sndscript.Level

Bases: Enum

Soundlevel constants - attenuation.

SNDLVL_NONE = 0

SNDLVL_IDLE = 60

SNDLVL_STATIC = 66

SNDLVL_NORM = 75

SNDLVL_TALKING = 80

SNDLVL_GUNFIRE = 140

classmethod parse(text: str) → int | Level: Parse a soundlevel string, which might be a SNDLVL name or a number.

classmethod parse_interval_kv( kv: Keyvalues, ) → tuple[int | Level, int | Level]

Parse an interval of attenuations from the soundlevel and attenuation keys of a keyvalues block.

Unlike others, this is rounded to an integer. Valve’s code only supports the SNDLVL names for a single value, but we allow it for an interval.

classmethod join_interval( interval: tuple[int | Level, int | Level], ) → str: Convert an interval back to a string. Valve requires full integers for intervals.

class srctools.sndscript.Volume

Bases: Enum

Special value, substitutes default volume (usually 1).

VOL_NORM = 'VOL_NORM'

classmethod parse_interval_kv( kv: Keyvalues, key: str = 'volume', ) → tuple[float | Volume, float | Volume]: Parse an interval of volumes from a subkey of a keyvalues block.

srctools.sndscript.VOL_NORM: This is available globally for convenience.

Sound

Represents a single soundscript.

name: str

sounds: list[str]

channel: int | Channel

force_v2: bool

volume: tuple[float | Volume, float | Volume]

level: tuple[int | Level, int | Level]

pitch: tuple[float | Pitch, float | Pitch]

property stack_start: Keyvalues: Initialise the stack if not already produced.

property stack_update: Keyvalues: Initialise the stack if not already produced.

property stack_stop: Keyvalues: Initialise the stack if not already produced.

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

Parses a soundscript file.

This returns a dict mapping casefolded names to Sounds.

classmethod parse_one(sound_kv: Keyvalues) → Sound: Parse a single soundscript definition.

export(file: FileWText) → None

Write a sound to a file.

Pass a file-like object open for text writing.

Sound Characters

srctools.sndscript.SND_CHARS: String with some operator characters. Deprecated, use SoundChars instead.

class srctools.sndscript.SoundChars

Bases: Flag

Flags to represent sound characters which can be added to the start of sound filenames.

Despite comments in the SDK, more than 2 are permitted simultaneously. To re-assemble into a set of characters, call str.

none = 0x0: A filename with no characters included.

stream = 0x1

user_vox = 0x2: Marks player voice chat data, shouldn’t ever be used.

sentence = 0x4: Dialog from the NPC sentence system.

dry_mix = 0x8: DSP FX is bypassed for this sound.

doppler = 0x10: Doppler encoded stereo wav: left wav (incoming) and right wav (outgoing).

directional = 0x20: Stereo wav has direction cone: mix left wav (front facing) with right wav (rear facing) based on sound facing direction

dist_variant = 0x40: Distance variant encoded stereo wav (left is close, right is far)

omni = 0x80: Non-directional - sound appears to play from everywhere, but still has distance volume falloff.

spatial_stereo = 0x100: Spatialised stereo wav

dir_stereo = 0x200: Directional stereo wav (like doppler)

fast_pitch = 0x400: Forces low quality, non-interpolated pitch shift

subtitled = 0x800: Indicates subtitles were forced on.

hrtf_force = 0x1000: CSGO+ only. Enables HRTF for all players including the owner.

hrtf = 0x2000: CSGO+ only. Enables HRTF for non-owners.

hrtf_blend = 0x4000: CSGO+ only. Enables HRTF for non-owner players, fading to stereo instead if close.

radio = 0x8000: CSGO+ only. Used for ‘radio’ sounds tha are played without spatialisation.

music = 0x10000: CSGO+ only. Used for main menu music.

classmethod from_fname(filename: str) → tuple[SoundChars, str]: Parse sound characters out of a filename, then return both.

Utilities

srctools.sndscript.parse_split_float( kv: Keyvalues, key: str, enum: Callable[[str], float | EnumT], default: float | EnumT, ) → tuple[float | EnumT, float | EnumT]

Parse pairs of float/enum values from keyvalues.

A single number can be provided, producing the same value for low and high.

Parameters:

kv – The keyvalues block for the sound, which key is then accessed from.
key – The name of the keyvalue to look up inside kv.
enum – This is either an Enum with values to match text constants, or a converter function returning enums or raising ValueError, KeyError or IndexError.
default – If either value or the whole string is unparsable, this default is used.

srctools.sndscript.split_float( value: str, enum: Callable[[str], float | EnumT], default: float | EnumT, ) → tuple[float | EnumT, float | EnumT]

Handle values which can be a low, high pair of numbers or enum constants.

A single number can be provided, producing the same value for low and high.

Parameters:

value – The value to read.
enum – This is either an Enum with values to match text constants, or a converter function returning enums or raising ValueError, KeyError or IndexError.
default – If either value or the whole string is unparsable, this default is used.

srctools.sndscript.join_float(val: tuple[float | Enum, float | Enum]) → str: Reverse split_float(). The two parameters should be stringifiable into floats/constants.

srctools.sndscript.wav_is_looped(file: FileRSeek[bytes]) → bool

Check if the provided wave file contains loop cue points.

This code is partially copied from wave.Wave_read.initfp().

srctools.sndscript.atten_to_level(attenuation: float) → int

Convert an old attenuation value to a soundlevel.

See ATTN_TO_SNDLVL in public/soundflags.h#L105 # TODO: Link that ^^