// ParseFilenameTimestamps parses timestamps from a batch of filenames.

// ParseFilenameTimestamps extracts timestamps from a batch of filenames using variance-based format detection.

// ParseFilenameTimestamps extracts timestamps from filenames using variance-based format detection

// ApplyTimezoneOffset applies a fixed timezone offset to timestamps
// Uses the EARLIEST (chronologically) timestamp to determine the offset, then applies it to all
// This matches AudioMoth behavior (no DST adjustment during deployment)
// ApplyTimezoneOffset converts local timestamps to location timezone with DST handling

// ApplyTimezoneOffset converts local timestamps to a location timezone with DST handling.
// Uses the EARLIEST (chronologically) timestamp to determine the offset, then applies it to all.
// This matches AudioMoth behavior (no DST adjustment during deployment).

// HasTimestampFilename checks if a filename matches the timestamp pattern
// HasTimestampFilename checks if filename contains a timestamp pattern

// HasTimestampFilename checks if a filename contains a timestamp pattern

// FileImportError records errors encountered during file processing
type FileImportError struct {
	FileName string `json:"file_name"`
	Error    string `json:"error"`
	Stage    string `json:"stage"` // "scan", "hash", "parse", "validate", "insert"
}

func ParseSpeciesCallType(s string) (species, callType string) {
	if s == "" {

func ParseSpeciesCallType(label string) (species, callType string) {
	if label == "" {

	if before, after, ok := strings.Cut(s, "+"); ok {

	if before, after, ok := strings.Cut(label, "+"); ok {

	return s, ""

	return label, ""

// FileImportError records errors encountered during file processing
type FileImportError struct {
	FileName string `json:"file_name"`
	Error    string `json:"error"`
	Stage    string `json:"stage"` // "scan", "hash", "parse", "validate", "insert"
}

			"SELECT EXISTS(SELECT 1 FROM file WHERE xxh64_hash = ?)",

			"SELECT EXISTS(SELECT 1 FROM file WHERE xxh64_hash = ? AND active = true)",

// IsAudioMoth checks if the comment or artist field indicates an AudioMoth recording
// IsAudioMoth detects if WAV file is from AudioMoth recorder

// IsAudioMoth detects if a WAV file is from an AudioMoth recorder by checking comment and artist fields

// ParseAudioMothComment parses structured AudioMoth comment field
// Returns parsed data or error if parsing fails
// ParseAudioMothComment extracts timestamp, gain, battery, and temperature from AudioMoth comment

// ParseAudioMothComment extracts timestamp, gain, battery, and temperature from an AudioMoth comment.

// parseLegacyComment parses older AudioMoth comment format (space-separated)

// parseLegacyComment parses older AudioMoth comment format (space-separated).

// Close stops playback and releases the oto context.
func (ap *AudioPlayer) Close() {
	ap.Stop()
}

// Close stops playback. The oto context is released by the garbage collector
// (oto v3 does not expose a context close method).

Here is a brief report based on a comprehensive review of the utils directory.
 ### 1. Duplicated Functionality
 - Audio Processing (Float64 to 16-bit PCM): wav_writer.go and audio_player.go contain identical,
 duplicated logic for converting float64 arrays into int16 LittleEndian bytes (including the [-1.0,
 1.0] bounds clamping and * 32767 scaling).
 - Timestamp Resolution Strategy: cluster_import.go (batchProcessFiles) manually reimplements the
 entire fallback chain for timestamp resolution (AudioMoth → Filename → File Modification Time). This
 exact logic is already neatly abstracted in file_import.go as ResolveTimestamp().
 - Directory Scanning: cluster_import.go implements its own scanClusterFiles to find .wav files, while
 data_file.go implements FindDataFiles to find .data files. These could be consolidated into a
 generic, reusable directory walker.

 ### 2. Untested Code

 Overall statement coverage for utils is at 46.5%. The following areas are completely untested (0%
 coverage):
 - Files with 0% coverage:
     - audio_player.go (Audio playback and context management)
     - config.go (JSON config file loading/parsing)
     - cluster_import.go (The core batch import logic and database transactions)
     - spectrogram.go (FFT operations, windowing, and image rendering)
     - wav_writer.go (WAV encoding logic)
 - Untested Critical Functions in otherwise tested files:
     - file_import.go: ProcessSingleFile, CheckDuplicateHash
     - mapping.go: ValidateMappingAgainstDB, Classify, ValidateCoversSpecies, Classes, Placeholders
     - validation.go: GetDatasetType, ValidateDatasetTypeForImport, ValidateDatasetTypeUnstructured,
 ValidateLocationBelongsToDataset