STSaveAudioParams
Configures the file produced by an audio-recording operation.
Overview
Configure where and how captured audio is saved, including its destination and requested output format. This is part of recording configuration, not a command to begin recording. Review the file type and format settings together so the requested combination is supported.
public struct STSaveAudioParams: Sendable {
public var fileType: STAudioFileType = .wav
public var fileBaseName: String = ""
public var destinationURL: URL?
public var audioFormat: STAudioFormat?
public var requestID: String = ""
public var includeTimestamp: Bool = false
}The default file type is WAV. audioFormat optionally requests a specific audio format. requestID provides application-supplied request identity associated with the saved output, and includeTimestamp controls whether timestamp information is included in generated naming behavior.
Properties
fileType— Output file type; defaults to .wav. Supported STAudioFileType cases are .wav, .caf, and .m4a.fileBaseName— Base name used for generated saved-audio filenames; defaults to an empty string. The final filename can also depend on the recording workflow.destinationURL— Optional destination URL for the saved audio. The calling workflow determines how a missing destination is resolved.audioFormat— Optional requested audio encoding format; ensure it is compatible with the selected file type.requestID— Application-provided request identifier used in naming or correlation when supported by the recording workflow; defaults to an empty string.includeTimestamp— Whether the generated name should include a timestamp when the workflow supports timestamp-based naming; defaults to false.
Saved-audio naming and recording workflows
The audio-file writer formats a provided filename using formattedFileName(originalFileName:requesterID:useTimestamp:). It takes the final path component, removes an existing recognized extension (wav, caf, or m4a, case-insensitively), appends an optional requester ID and timestamp, then restores the recognized extension in lowercase.
<baseName>[_<requesterID>][_<timestamp>][.<recognizedExtension>]
The requester ID is appended when it contains non-whitespace characters; the original untrimmed ID string is used. A timestamp is appended only when requested, using yyyy-MM-dd'-T-'HH-mm-ss-SSS in the date formatter's configured locale/time zone. Unrecognized extensions are retained as part of the base name, not stripped or restored by this formatter. This function does not independently append a new file-type extension when none was recognized.
Conversation recording filenames
For ordinary audio recording (.CFT_RecordAudio), the conversation runner uses audioRecording.recordingOutput.fileName. If empty after trimming, it uses RecordAudio_<timestamp> and marks the timestamp as already used. Otherwise, it applies runtime-field mapping and trims the result.
For speech-recognition utterance recording (.CFT_RecordUtterance), the same configured filename source and field-mapping rule apply. The empty-name fallback is RecordUtterance_<timestamp>, likewise marking the timestamp as already used. These fallback names do not include an extension at this stage; subsequent writer configuration determines the output file type.
If utterance saving is disabled, the pre-trim path argument is an empty string. The existing timeStampUsed flag is forwarded unchanged. This function constructs and passes the path; it does not itself establish when writing starts, whether further filename processing occurs, or the final extension. Pre-trim utterance output is distinct from the separately configured pre-VAD audio recording described below.
var recordUtterancePreTrimSilFilePathName: String? = nil
if m_bSaveUtteranceAudio {
recordUtterancePreTrimSilFilePathName =
audioRecordingForRecognize.recordingOutput!.resourceLocation!
+ "/PreTrimSil_"
+ audioRecordingForRecognize.recordingOutput!.fileName!
}
return GetAudioRecordParams(
audioRecordingForRecognize,
recordUtterancePreTrimSilFilePathName ?? "",
timeStampUsed
)
In the conversation runner, getAudioRecordParams(_ audioRecordingForRecognize: AudioRecording, timeStampUsed: Bool) prepares an optional pre-trim utterance file path. When m_bSaveUtteranceAudio is enabled, the path is constructed by joining the configured audioRecordingForRecognize.recordingOutput.resourceLocation, a slash, PreTrimSil_, and the configured audioRecordingForRecognize.recordingOutput.fileName. For example, a configured directory /recordings and filename utterance.wav yield /recordings/PreTrimSil_utterance.wav at this stage.
Pre-trim utterance recording filename
Pre-VAD audio recording
When VAD is enabled, passive audio recording is disabled, and vadParams.preVADAudioFileName is non-nil, the recorder attempts a separate pre-VAD file write using the same saveAudioParams and the supplied pre-VAD name as overrideFileName. If writer startup succeeds, pre-VAD recording is activated and a completion callback is installed. This can preserve audio before VAD silence trimming.
Speech-synthesis recording
Speech-synthesis output is configured through STSSRecordParams, not this type. Its extension-handling path is separate from the audio writer formatter: for example, requesting WAV output for welcome.caf can produce welcome.caf.wav. Do not apply the formatter's recognized-extension replacement rule to speech-synthesis output.