Android-247-Radio/docs/plans/2026-03-10-settings-panel-design.md

Settings Panel Design

Overview

Add four new feature sections to the existing SettingsScreen: SomaFM quality preference, now-playing history file logging, reset customizations, and restart app.

1. SomaFM Quality Preference

Data Model

New station_streams table:

Column	Type	Notes
id	Long PK	Auto-generated
stationId	Long FK	References stations.id
bitrate	Int	128 or 256
ssl	Boolean	true = HTTPS, false = HTTP
url	String	Full stream URL

URL patterns:

• SSL: https://ice1.somafm.com/{streamId}-{bitrate}-mp3
• Non-SSL: http://ice1.somafm.com/{streamId}-{bitrate}-mp3

Stations with only 128kbps support get 2 rows; stations with 256kbps get 4 rows.

Preference Storage

• Global preference in RadioPreferences: ordered list stored as JSON string, e.g. ["256-ssl","256-nossl","128-ssl","128-nossl"]. Users can reorder in settings.
• Per-station override: nullable qualityOverride column on Station. When non-null, overrides the global preference with the same JSON format. When null, uses the global default.

Playback Resolution

New StreamResolver utility:

1. Queries station_streams for the station's available streams.
2. Orders them by the applicable preference (per-station override or global default).
3. Returns the first URL. On connection failure, AudioEngine/RadioPlaybackService tries the next URL in the chain.

Non-SomaFM stations use station.url directly — no streams table involvement.

Settings UI

• Draggable list showing the 4 quality tiers in current preference order
• Per-station: accessible from station long-press menu or edit dialog

2. Now Playing History (File Logging)

Preference Keys in RadioPreferences

• historyEnabled: Boolean — default false
• historyFormat: String — "csv", "json", or "plain" (default "csv")
• historyFilePath: String — default: app's external files directory

File Formats

• CSV: "2026-03-10 09:30:15","Groove Salad","Tycho","A Walk"
• JSON lines: {"timestamp":"2026-03-10T09:30:15","station":"Groove Salad","artist":"Tycho","title":"A Walk"}
• Plain text: 2026-03-10 09:30 | Groove Salad | Tycho - A Walk

File names: now-playing-history.csv, .jsonl, or .txt based on format.

Writer

NowPlayingHistoryWriter class:

• Called from RadioPlaybackService after metadataSnapshotDao.insert() when ICY metadata changes
• Checks historyEnabled preference; if true, appends a line to the file in the chosen format
• Thread-safe file writes on Dispatchers.IO

Settings UI

• Toggle: "Enable Now Playing History"
• Dropdown/chips: format selector (CSV, JSON, Plain Text)
• Current path display + "Choose Directory" button (launches ACTION_OPEN_DOCUMENT_TREE)

3. Reset Customizations

Behavior

A "Reset All Customizations" button with a companion toggle: "Also delete saved stations/playlists".

Confirmation dialog adapts its message based on the toggle state.

Always resets (in a single DB transaction):

• starred = false on all stations
• sortOrder restored to original seed index
• isHidden = false on all stations
• qualityOverride = null on all stations

If toggle is on, also:

• Deletes all non-built-in playlists and their stations

Error handling:

• Wrapped in try/catch
• Shows a Toast on failure
• Fails gracefully — partial reset should not corrupt state (transaction rollback)

4. Restart App

Behavior

A "Restart App" button that:

1. Calls RadioController.stop() for graceful shutdown
2. Waits up to 3 seconds for PlaybackState.Idle
3. If still not idle, force-stops the service via stopService()
4. Restarts: launches MainActivity with FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_CLEAR_TASK, then Runtime.getRuntime().exit(0)

No external libraries needed.

Files Affected

New files:

• data/model/StationStream.kt — Room entity
• data/db/StationStreamDao.kt — DAO
• service/StreamResolver.kt — URL resolution logic
• data/logging/NowPlayingHistoryWriter.kt — file logger

Modified files:

• data/model/Station.kt — add qualityOverride column
• data/db/RadioDatabase.kt — add entity, bump version, add migration
• data/db/SomaFmSeedData.kt — seed station_streams rows
• data/prefs/RadioPreferences.kt — add quality, history prefs
• service/RadioPlaybackService.kt — use StreamResolver, call history writer
• ui/screens/settings/SettingsScreen.kt — add all 4 new sections
• ui/screens/settings/SettingsViewModel.kt — add reset/restart/quality/history logic
• RadioApplication.kt — expose history writer