File      string `json:"file" jsonschema:"Path to .data file (required if no folder)"`
	Folder    string `json:"folder" jsonschema:"Path to folder containing .data files (required if no file)"`
	Output    string `json:"output" jsonschema:"required,Output folder for generated clips"`
	Prefix    string `json:"prefix" jsonschema:"required,Prefix for output filenames"`
	Filter    string `json:"filter" jsonschema:"Filter by ML model name"`
	Species   string `json:"species" jsonschema:"Filter by species, optionally with calltype (e.g. Kiwi, Kiwi+Duet)"`
	Certainty int    `json:"certainty" jsonschema:"Filter by certainty value (0-100, -1 for no filter)"`
	Size      int    `json:"size" jsonschema:"Spectrogram image size in pixels (224-896, default 224)"`
	Color     bool   `json:"color" jsonschema:"Apply L4 colormap to spectrogram (default: grayscale)"`
	WavOnly   bool   `json:"wav_only" jsonschema:"Generate only WAV clips, skip spectrogram PNG generation"`

	File      string  `json:"file" jsonschema:"Path to .data file (required if no folder)"`
	Folder    string  `json:"folder" jsonschema:"Path to folder containing .data files (required if no file)"`
	Output    string  `json:"output" jsonschema:"required,Output folder for generated clips"`
	Prefix    string  `json:"prefix" jsonschema:"required,Prefix for output filenames"`
	Filter    string  `json:"filter" jsonschema:"Filter by ML model name"`
	Species   string  `json:"species" jsonschema:"Filter by species, optionally with calltype (e.g. Kiwi, Kiwi+Duet)"`
	Certainty int     `json:"certainty" jsonschema:"Filter by certainty value (0-100, -1 for no filter)"`
	Size      int     `json:"size" jsonschema:"Spectrogram image size in pixels (224-896, default 224)"`
	Color     bool    `json:"color" jsonschema:"Apply L4 colormap to spectrogram (default: grayscale)"`
	WavOnly   bool    `json:"wav_only" jsonschema:"Generate only WAV clips, skip spectrogram PNG generation"`
	Night     bool    `json:"night" jsonschema:"Only clip recordings made during solar night (requires Lat and Lng)"`
	Lat       float64 `json:"lat" jsonschema:"Latitude for night filtering (required with Night)"`
	Lng       float64 `json:"lng" jsonschema:"Longitude for night filtering (required with Night)"`
	Timezone  string  `json:"timezone" jsonschema:"IANA timezone ID for filename timestamps (e.g. Pacific/Auckland). Required for non-AudioMoth recorders when using --night"`

	NightSkipped    int      `json:"night_skipped,omitempty"`

			clips, errs := processFile(dataPath, input.Output, input.Prefix, input.Filter, speciesName, callType, input.Certainty, imgSize, input.Color, input.WavOnly)

			clips, skipped, errs := processFile(dataPath, input.Output, input.Prefix, input.Filter, speciesName, callType, input.Certainty, imgSize, input.Color, input.WavOnly, input.Night, input.Lat, input.Lng, input.Timezone)

			output.NightSkipped += skipped

			clips []string
			errs  []string

			clips   []string
			skipped int
			errs    []string

					clips, errs := processFile(dataPath, input.Output, input.Prefix, input.Filter, speciesName, callType, input.Certainty, imgSize, input.Color, input.WavOnly)
					results <- fileResult{clips: clips, errs: errs}

					clips, skipped, errs := processFile(dataPath, input.Output, input.Prefix, input.Filter, speciesName, callType, input.Certainty, imgSize, input.Color, input.WavOnly, input.Night, input.Lat, input.Lng, input.Timezone)
					results <- fileResult{clips: clips, skipped: skipped, errs: errs}

			output.NightSkipped += r.skipped

// processFile processes a single .data file and returns generated clips and errors
func processFile(dataPath, outputDir, prefix, filter, speciesName, callType string, certainty, imgSize int, color, wavOnly bool) ([]string, []string) {

// processFile processes a single .data file and returns generated clips, night-skipped count, and errors
func processFile(dataPath, outputDir, prefix, filter, speciesName, callType string, certainty, imgSize int, color, wavOnly, night bool, lat, lng float64, timezone string) ([]string, int, []string) {

		return nil, errors

		return nil, 0, errors

		return nil, nil // No matches, not an error

		return nil, 0, nil // No matches, not an error
	}
	// Night filter: check WAV header only (cheaper than reading full audio).
	// Skip daytime recordings before paying the cost of ReadWAVSamples.
	if night {
		result, err := IsNight(IsNightInput{
			FilePath: wavPath,
			Lat:      lat,
			Lng:      lng,
			Timezone: timezone,
		})
		if err != nil {
			fmt.Fprintf(os.Stderr, "warning: skipping %s (isnight error: %v)\n", wavPath, err)
			return nil, 0, nil
		}
		if !result.SolarNight {
			fmt.Fprintf(os.Stderr, "skipped (daytime): %s\n", wavPath)
			return nil, 1, nil
		}

		return nil, errors

		return nil, 0, errors

	return clips, errors

	return clips, 0, errors

skraak calls clip --folder F09/2026-04-06/ --prefix tst --output "/home/david/test/"  --species Kiwi --filter opensoundscape-kiwi-1.2 --size 224 --color

"z": ""Don't Know"",

"z": "Don't Know",

	fmt.Fprintf(os.Stderr, "  --night            Only clip recordings made during solar night (requires --lat and --lng)\n")
	fmt.Fprintf(os.Stderr, "  --lat <float>      Latitude in decimal degrees (required with --night)\n")
	fmt.Fprintf(os.Stderr, "  --lng <float>      Longitude in decimal degrees (required with --night)\n")
	fmt.Fprintf(os.Stderr, "  --timezone <zone>  IANA timezone ID (e.g. Pacific/Auckland). Required for non-AudioMoth\n")
	fmt.Fprintf(os.Stderr, "                     recorders whose filenames embed local time (e.g. DOC AR4).\n")
	fmt.Fprintf(os.Stderr, "                     AudioMoth files embed a UTC timestamp in the WAV comment, so\n")
	fmt.Fprintf(os.Stderr, "                     --timezone is not needed for AudioMoth data.\n")

	var file, folder, output, prefix, filter, species string

	var file, folder, output, prefix, filter, species, timezone string

	var color, wavOnly bool

	var color, wavOnly, night bool
	var lat, lng float64
	var latSet, lngSet bool

			i++
		case "--night":
			night = true

		case "--lat":
			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --lat requires a value\n")
				os.Exit(1)
			}
			v, err := strconv.ParseFloat(args[i+1], 64)
			if err != nil {
				fmt.Fprintf(os.Stderr, "Error: --lat must be a number\n")
				os.Exit(1)
			}
			lat = v
			latSet = true
			i += 2

		case "--lng":
			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --lng requires a value\n")
				os.Exit(1)
			}
			v, err := strconv.ParseFloat(args[i+1], 64)
			if err != nil {
				fmt.Fprintf(os.Stderr, "Error: --lng must be a number\n")
				os.Exit(1)
			}
			lng = v
			lngSet = true
			i += 2
		case "--timezone":
			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --timezone requires a value\n")
				os.Exit(1)
			}
			timezone = args[i+1]
			i += 2

	if night && (!latSet || !lngSet) {
		fmt.Fprintf(os.Stderr, "Error: --night requires both --lat and --lng\n\n")
		printClipUsage()
		os.Exit(1)
	}

		Night:     night,
		Lat:       lat,
		Lng:       lng,
		Timezone:  timezone,

# Works for audiomoth which records time metadata as UTC

# DOC recorders record local time without timezone, IANA timezone required

## [2026-04-18] `calls clip --night`: filter to solar-night recordings only
Adds `--night`, `--lat`, `--lng`, and `--timezone` flags to `skraak calls clip`.
When `--night` is set, each recording is checked against solar sunrise/sunset at
the given coordinates before its audio is loaded — daytime files are skipped
entirely, saving the cost of reading WAV audio for files that would produce no
useful clips.
`--timezone` is not needed for AudioMoth recorders (timestamp comes from the WAV
comment in UTC). It is required for recorders that embed **local time** in the
filename (e.g. DOC AR4) — without it the filename is parsed as UTC and
`solar_night` will be wrong. Pass `--timezone Pacific/Auckland` or the
appropriate IANA zone.
The JSON output gains a `night_skipped` field (omitted when 0) counting how many
files were filtered out. Skipped filenames are logged to stderr.
```bash
skraak calls clip --folder ./data --output ./clips --prefix kiwi \
  --species Kiwi --night --lat -40.85 --lng 172.81
# Non-AudioMoth (DOC AR4, filename in local time):
skraak calls clip --folder ./data --output ./clips --prefix kiwi \
  --species Kiwi --night --lat -40.85 --lng 172.81 --timezone Pacific/Auckland
```
**Files changed:**
- `tools/calls_clip.go` — `CallsClipInput` (Night/Lat/Lng/Timezone fields),
  `CallsClipOutput` (NightSkipped field), `processFile` night-filter block.
- `cmd/calls_clip.go` — flag parsing, `--night` requires lat/lng validation,
  updated usage/help text.