Add --low-power flag to disable visualizer

Sets cfg.Visualizer = "none" so the tick loop falls back to TickSlow
(5 FPS for time/seek display only). Targets battery, slow terminals,
and SSH sessions where the spectrum redraw + FFT pipeline is the
dominant CPU cost. Press v in the player to cycle the visualizer
back on at any time.

Author: bjarneo

commands.go

@@ -43,6 +43,7 @@ func buildApp() *cli.Command {
 		&cli.StringFlag{Name: "audio-device", Usage: "audio output device (use 'list' to show)"},
 		&cli.StringFlag{Name: "playlist", Usage: "load a local TOML playlist by name and start playing"},
 		&cli.StringFlag{Name: "log-level", Usage: "log level: debug, info, warn, error"},
+		&cli.BoolFlag{Name: "low-power", Usage: "low-power mode: disable visualizer to minimize CPU"},
 	}
 
 	return &cli.Command{
@@ -195,6 +196,10 @@ func overridesFromFlags(c *cli.Command) (config.Overrides, error) {
 		}
 		ov.LogLevel = &v
 	}
+	if c.IsSet("low-power") {
+		v := c.Bool("low-power")
+		ov.LowPower = &v
+	}
 	return ov, nil
 }
 

config/flags.go

@@ -19,6 +19,7 @@ type Overrides struct {
 	AudioDevice     *string
 	Playlist        *string
 	LogLevel        *string
+	LowPower        *bool
 }
 
 // Apply merges non-nil overrides into cfg and clamps the result.
@@ -74,5 +75,11 @@ func (o Overrides) Apply(cfg *Config) {
 	if o.LogLevel != nil {
 		cfg.LogLevel = *o.LogLevel
 	}
+	if o.LowPower != nil && *o.LowPower {
+		// Low-power mode disables the visualizer entirely. With Mode = None,
+		// the tick loop falls back to TickSlow (5 FPS) for time/seek display
+		// only — the dominant CPU sink for the TUI.
+		cfg.Visualizer = "none"
+	}
 	cfg.clamp()
 }

docs/cli.md

@@ -38,6 +38,14 @@ cliamp --log-level debug                     # raise log verbosity for one sessi
 
 Logs are written to `~/.config/cliamp/cliamp.log`. Levels: `debug`, `info` (default), `warn`, `error`.
 
+## Low-power mode
+
+```sh
+cliamp --low-power track.mp3                 # minimize CPU: visualizer off
+```
+
+Forces the visualizer to `none` so the TUI ticks at 5 FPS for the time/seek display only. Useful on battery, slow terminals, or SSH sessions. Press `v` in the player to cycle visualizers back on at any time.
+
 ## Search
 
 Search and play a track directly from the command line (requires [yt-dlp](https://github.com/yt-dlp/yt-dlp)):
@@ -84,6 +92,7 @@ cliamp track.mp3 --repeat all --mono ~/Music
 | `--bit-depth` | int | 16 | 16, 32 |
 | `--playlist` | string | | local TOML playlist name |
 | `--log-level` | string | info | debug, info, warn, error |
+| `--low-power` | bool | false | disables visualizer; cuts redraw + FFT cost |
 
 CLI flags override config file values for the current session only. They are not persisted.
 

site/index.html

@@ -2014,6 +2014,7 @@ <h3>Run the setup wizard</h3>
           <div class="key-row"><kbd>--resample-quality &lt;n&gt;</kbd><span>1–4</span></div>
           <div class="key-row"><kbd>--bit-depth &lt;n&gt;</kbd><span>PCM: 16 or 32</span></div>
           <div class="key-row"><kbd>--compact</kbd><span>Cap width at 80 cols</span></div>
+          <div class="key-row"><kbd>--low-power</kbd><span>Disable visualizer to save CPU</span></div>
           <div class="key-row"><kbd>--playlist &lt;name&gt;</kbd><span>Load TOML playlist</span></div>
           <div class="key-row"><kbd>--provider &lt;name&gt;</kbd><span>Default provider</span></div>
           <div class="key-row"><kbd>--upgrade</kbd><span>Update in place</span></div>