README
¶
Recording
Package recording provides conversation audio recording to local WAV files and async upload to S3 via a worker pool.
Purpose
- ConversationRecorder: Records mixed PCM 16-bit mono samples for a single session;
WriteSamplesappends audio;Closefinalizes the WAV file and returnsLocalFileInfo. - Uploader: Accepts
RecordingJob(local path, bucket, key); worker pool uploads to S3 and removes the local file on success. Used when a session ends: recorder is closed, then a job is enqueued.
Exported symbols
| Symbol | Type | Description |
|---|---|---|
ConversationRecorder |
interface | WriteSamples(samples []int16, sampleRate int) error, Close() (LocalFileInfo, error) |
LocalFileInfo |
struct | Path, StartedAt, EndedAt, Format |
NewFileRecorder |
func | Creates a file-based recorder writing <dir>/<base>.wav; writes empty WAV header, finalizes on Close |
RecordingJob |
struct | LocalPath, Bucket, Key |
Uploader |
struct | S3 upload worker pool; NewUploader, Enqueue, Shutdown |
NewUploader |
func | Builds uploader with AWS default config; starts workerCount goroutines reading from job queue |
BuildS3Key |
func | Builds key basePath/yyyy/mm/dd/<callID>.<format> |
Data flow
flowchart LR
Session["Session\nmixed PCM"] --> Recorder["ConversationRecorder\nWriteSamples"]
Recorder --> Close["Close"]
Close --> WAV["Local WAV file"]
WAV --> Enqueue["Uploader.Enqueue"]
Enqueue --> Queue["Job queue"]
Queue --> Workers["Worker pool"]
Workers --> S3["S3 PutObject"]
S3 --> Remove["Remove local file"]
- Session end: caller closes the recorder (get
LocalFileInfo), buildsRecordingJobwith path, bucket, key (e.g. viaBuildS3Key), thenUploader.Enqueue(job). - Workers pull jobs from the channel and upload; on success the local file is removed. Metrics:
RecordingJobsEnqueuedTotal,RecordingJobsSuccessTotal,RecordingJobsFailedTotal,RecordingQueueDepth.
Concurrency
- ConversationRecorder: Intended for single-goroutine use (e.g. one recorder per session).
- Uploader:
Enqueueis safe for concurrent use;Shutdowncloses the job channel and waits for workers (or ctx done). Worker goroutines run until the job channel is closed.
Files
| File | Description |
|---|---|
recorder.go |
ConversationRecorder, LocalFileInfo, NewFileRecorder, fileRecorder impl |
wav.go |
WAV header write and finalize (internal) |
uploader.go |
RecordingJob, Uploader, NewUploader, Enqueue, Shutdown, BuildS3Key, worker loop |
See also
- ../metrics/README.md — Recording metrics
- ../config/README.md — Recording config (bucket, base_path, worker_count)
- ../../docs/ARCHITECTURE.md — Pipeline and session flow
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ConversationRecorder ¶
type ConversationRecorder interface {
// WriteSamples appends raw PCM 16-bit mono samples at the given sample rate.
WriteSamples(samples []int16, sampleRate int) error
// Close finalizes the recording and returns info about the created file.
Close() (LocalFileInfo, error)
}
ConversationRecorder records mixed audio for a single call/session. Implementations are expected to be safe for use from a single goroutine.
func NewFileRecorder ¶
func NewFileRecorder(dir, base string, sampleRate int) (ConversationRecorder, error)
NewFileRecorder creates a new file-based recorder writing a WAV file in dir with the given basename. The final filename will be "<base>.wav".
type LocalFileInfo ¶
LocalFileInfo describes a finalized local recording file.
type RecordingJob ¶
RecordingJob describes a finalized recording to upload.
type Uploader ¶
type Uploader struct {
// contains filtered or unexported fields
}
Uploader uploads recordings to S3 using a fixed-size worker pool. THREAD SAFETY: Enqueue may be called from any goroutine; workers are the only consumers of jobs; Shutdown must not be called concurrently with Enqueue.
func NewUploader ¶
NewUploader creates a new uploader with the given worker count, queue size, and max retries (0 = default 3). SCALING: one worker per ~N concurrent sessions uploading at once; tune for S3 bandwidth.
func (*Uploader) Enqueue ¶
func (u *Uploader) Enqueue(job RecordingJob) error
Enqueue adds a job to the upload queue.
Source Files