feat(audio): add audio fading capabilities with configurable duration (in settings)

.gitignore

@@ -1,3 +1,12 @@
+# Meta / Tooling
+.gitignore
+.agents/
+.shreakter.json
+projectdata/
+test_ui/
+Assets/
+
+
 # Build artifacts
 .build/
 DerivedData/
@@ -66,3 +75,4 @@ TEMP_*
 build/
 .codex/environments/environment.toml
 Build
+.gitignore

README.md

@@ -1,93 +1,99 @@
-<h1 align="center">Kaset</h1>
+<img src="docs/screenshots/app-icon.png" width="84" height="84" alt="Kaset App Icon">
 
-<p align="center">A native macOS client for YouTube Music and YouTube, built with Swift and SwiftUI.</p>
+# Kaset — In-Engine Audio Fading
 
-<p align="center">
-  <a href="https://trendshift.io/repositories/16570?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-16570"><img src="https://trendshift.io/api/badge/repositories/16570" alt="sozercan/kaset | Trendshift" width="200" height="44"/></a>
+Smooth volume fading and crossfading transitions for Kaset on macOS.
+
+---
+
+## Overview
+
+Abrupt stops and starts during audio playback can feel jarring. This branch adds smooth audio fading directly into the player, easing the volume down when you pause or skip and fading it back in when you hit play.
+
+<p align="left">
+  <img src="docs/screenshots/settings-audio-dark.png" alt="Audio Fading Settings" width="600">
 </p>
 
+---
+
+## Audio Comparison: Fade vs. No Fade
+
+Listen to the difference in playback transitions:
+
 <table>
   <tr>
-    <th>YouTube Music</th>
-    <th>YouTube</th>
+    <th width="50%">With In-Engine Audio Fade</th>
+    <th width="50%">Without Audio Fade (Abrupt Cut)</th>
+  </tr>
+  <tr>
+    <td valign="top">
+      <audio controls src="docs/audio/fade.wav"></audio>
+      <br><br>
+      <a href="docs/audio/fade.wav">Listen / Download <code>fade.wav</code></a>
+    </td>
+    <td valign="top">
+      <audio controls src="docs/audio/no-fade.wav"></audio>
+      <br><br>
+      <a href="docs/audio/no-fade.wav">Listen / Download <code>no-fade.wav</code></a>
+    </td>
   </tr>
   <tr>
-    <td><img src="docs/screenshot-ytm.png" alt="Kaset YouTube Music screenshot"></td>
-    <td><img src="docs/screenshot-yt.png" alt="Kaset YouTube screenshot"></td>
+    <td valign="top">Volume smoothly eases down when pausing and fades back in naturally on play.</td>
+    <td valign="top">Audio immediately cuts out with an abrupt stop.</td>
   </tr>
 </table>
 
-## Features
-
-### Music & Video
+---
 
-- 🎵 **Native macOS Experience** — Apple Music-style UI with Liquid Glass player bars, clean sidebar navigation, and a source toggle for Music ↔ YouTube
-- 🎧 **YouTube Music Support** — Full playback of DRM-protected YouTube Music content via your existing Premium subscription
-- ▶️ **[YouTube Support](docs/youtube.md)** — Browse regular YouTube recommendations, search, subscriptions, Shorts, Watch Later, history, comments, and video playback with native controls, captions, quality selection, and picture in picture
+## Fading Curves & Mathematics
 
-### Playback
+Human hearing perceives volume changes on a curve rather than in a straight line. If you change volume linearly, the music feels like it drops too quickly at the start and hangs around too long at the end. To make transitions feel natural, Kaset uses smooth curve formulas for fading.
 
-- 🎚️ **Equalizer** — System-wide 6-band parametric EQ with Spotify-style presets, applied to WebKit playback output
-- 📜 **Lyrics** — View plain and synced lyrics with line-by-line highlighting when timing data is available, plus AI-powered explanations and mood analysis on macOS 26+
-- 📃 **Queue Management** — View, reorder, shuffle, and clear your playback queue
-- 🔀 **Smart Shuffle** — Beyond plain shuffle: blends suggested tracks into the queue based on what you're playing, with cadence and how many are queued ahead configurable in Settings
-- 🔊 **Background Audio** — Music continues playing when the window is closed; stops on quit
-- 🎶 **Track Notifications** — Get notified when a new track starts playing
+For elapsed time $t$ over a target fade duration $T$, progress $p$ from start to finish is:
 
-### Library & Discovery
+$$
+p = \min\left(1.0, \frac{t}{T}\right) \quad \text{where } p \in [0, 1]
+$$
 
-- 📚 **Library Access** — Browse playlists, liked songs, and subscribed podcasts; create playlists, add songs to playlists, and delete your own playlists
-- 🧭 **Explore** — Discover new releases, charts, and moods & genres
-- 🎙️ **Podcasts** — Browse and listen to podcasts with episode progress tracking
-- 🔍 **Search** — Find songs, albums, artists, playlists, and podcasts
-- 🕓 **History** — Revisit recently played tracks
+### Volume Rise (Fade-In)
+When starting or resuming playback, the volume ramps up from starting level $V_{\text{start}}$ to your set volume $V_{\text{target}}$:
 
-### macOS Integration
+$$
+V_{\text{in}}(p) = V_{\text{start}} + (V_{\text{target}} - V_{\text{start}}) \cdot p^{\,2.2}
+$$
 
-- 🎛️ **System Integration** — Now Playing in Control Center, media key support, Dock menu controls
-- ✨ **Apple Intelligence** — On-device AI for natural language commands, lyrics explanations, and playlist refinement on macOS 26+
-- ⌨️ **[Keyboard Shortcuts](docs/keyboard-shortcuts.md)** — Full keyboard control for playback, navigation, and more
-- 📳 **Haptic Feedback** — Tactile feedback on Force Touch trackpads for player controls and navigation
-- 📣 **Share** — Share songs, playlists, albums, and artists via the native macOS share sheet
-- 🌍 **Localized** — UI available in 17 languages (Arabic, Chinese (Simplified), Chinese (Traditional), Dutch, English, French, German, Indonesian, Italian, Korean, Polish, Portuguese, Russian, Spanish, Swedish, Turkish, Ukrainian); change under Settings → General → Language
+Using an exponent of $\gamma = 2.2$ gives a gentle initial start that rises smoothly to your normal volume without sudden jumps.
 
-### Automation & Extensibility
+### Volume Decay (Fade-Out)
+When pausing, skipping, or seeking, the volume fades down to zero:
 
-- 🧩 **[Extensions](docs/extensions.md)** — Load WebKit Web Extensions, including [uBlock Origin Lite](https://github.com/uBlockOrigin/uBOL-home) and [SponsorBlock](https://github.com/ajayyy/SponsorBlock)
-- 🔗 **[URL Scheme](docs/url-scheme.md)** — Open songs directly with `kaset://play?v=VIDEO_ID`; app-targeted YouTube watch and `youtu.be` links play in YouTube mode
-- 🤖 **[AppleScript Support](docs/applescript.md)** — Automate playback with scripts, Raycast, Alfred, and Shortcuts
+$$
+V_{\text{out}}(p) = V_{\text{start}} \cdot (1 - p)^{2.0}
+$$
 
-## Requirements
+A curve exponent of $\gamma = 2.0$ makes sure the music smoothly fades out to silence without any harsh cutoffs at the end.
 
-- macOS 15.4 or later
-- Apple Intelligence features require macOS 26.0 or later
-- [Google](https://accounts.google.com) account for YouTube Music and YouTube personalization
+---
 
-## Installation
+## Key Features
 
-### Download
+- **Natural Volume Curves**: Uses smooth curve math calibrated for human hearing so fades sound natural.
+- **Glitch-Free Controls**: Handles rapid play/pause clicks and quick skips smoothly without volume spikes or audio glitches.
+- **Customizable Preferences**: Easily adjust fade duration or turn it off completely in Settings → Music → Audio.
+- **Automated Tests**: Backed by unit tests covering curve calculations, rapid button presses, and volume restoration.
 
-Download the latest release from the [Releases](https://github.com/sozercan/kaset/releases) page.
+---
 
-### Homebrew
+## Building from Source
 
 ```bash
-brew install sozercan/repo/kaset
-```
-
-> **Note:** The app is not signed.
-> If you downloaded the app manually, you can clear extended attributes (including quarantine) with:
->
-> ```bash
-> xattr -cr /Applications/Kaset.app
-> ```
+# Clone the feature branch
+git clone -b feature/audio-fade https://github.com/httperry/Kaset.git
+cd Kaset
 
-## Contributing
+# Build the project
+swift build
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture, and coding guidelines.
-
-We welcome AI-assisted contributions! You can submit traditional PRs or **prompt requests** — share the AI prompt that generates your changes, and maintainers can review the intent before running the code. See the [AI-Assisted Contributions](CONTRIBUTING.md#ai-assisted-contributions--prompt-requests) section for details.
-
-## Disclaimer
-
-Kaset is an unofficial application and not affiliated with YouTube or Google Inc. in any way. "YouTube", "YouTube Music" and the "YouTube Logo" are registered trademarks of Google Inc.
+# Package and run the app bundle
+./Scripts/compile_and_run.sh --debug
+```

Sources/Kaset/AppDelegate.swift

@@ -372,6 +372,32 @@ extension AppDelegate: NSWindowDelegate {
         sender.orderOut(nil)
         return false // Don't actually close
     }
+
+    // MARK: - Fullscreen Transitions
+
+    func windowDidEnterFullScreen(_ notification: Notification) {
+        guard let window = notification.object as? NSWindow,
+              MainWindowLayout.isPrimaryWindow(window)
+        else { return }
+        // macOS handles the autohiding titlebar + traffic lights natively in fullscreen.
+        // Keep titlebar transparent so the native overlay blends cleanly.
+        window.titleVisibility = .hidden
+        window.titlebarAppearsTransparent = true
+        window.titlebarSeparatorStyle = .none
+    }
+
+    func windowDidExitFullScreen(_ notification: Notification) {
+        guard let window = notification.object as? NSWindow,
+              MainWindowLayout.isPrimaryWindow(window)
+        else { return }
+        // macOS may reset titlebar properties during the fullscreen transition.
+        // Re-apply windowed appearance after exiting.
+        MainWindowLayout.restoreWindowedAppearance(window)
+    }
+
+    // MARK: - Resize
+
+    func windowDidResize(_: Notification) {}
 }
 
 // MARK: UNUserNotificationCenterDelegate

Sources/Kaset/Services/AudioFadeCoordinator.swift

@@ -0,0 +1,89 @@
+import Foundation
+import WebKit
+
+/// Central coordinator for player audio fading state, track crossfading, and background audio ducking.
+@MainActor
+final class AudioFadeCoordinator {
+    static let shared = AudioFadeCoordinator()
+
+    /// Current audio ducking state for background system events.
+    private(set) var isDucked: Bool = false
+    private var preDuckVolume: Double = 1.0
+
+    private init() {}
+
+    /// Performs a crossfade transition between currently playing track and next track.
+    func crossfadeTrackTransition(
+        webView: WKWebView?,
+        duration: TimeInterval = 1.5,
+        curve: AudioFaderService.FadeCurve = .logarithmic,
+        onNextTrackReady: @escaping @MainActor () -> Void
+    ) {
+        guard let webView else {
+            onNextTrackReady()
+            return
+        }
+
+        // Step 1: Smoothly fade out current track
+        AudioFaderService.shared.fadeOut(
+            webView: webView,
+            duration: duration / 2.0,
+            curve: curve
+        ) {
+            // Step 2: Trigger track change callback once volume is silenced
+            onNextTrackReady()
+
+            // Step 3: Smoothly fade back in for new track
+            AudioFaderService.shared.fadeIn(
+                webView: webView,
+                targetVolume: 1.0,
+                duration: duration / 2.0,
+                curve: curve
+            )
+        }
+    }
+
+    /// Smoothly ducks playback volume when system notifications or notifications play.
+    func duckAudio(
+        webView: WKWebView?,
+        targetDuckedVolume _: Double = 0.25,
+        duration: TimeInterval = 0.4
+    ) {
+        guard let webView, !self.isDucked else { return }
+
+        self.isDucked = true
+        self.preDuckVolume = 1.0
+
+        let script = "if (document.querySelector('video')) { document.querySelector('video').volume; }"
+        webView.evaluateJavaScript(script) { result, _ in
+            if let currentVol = result as? Double {
+                Task { @MainActor in
+                    AudioFadeCoordinator.shared.preDuckVolume = currentVol
+                    AudioFaderService.shared.fadeOut(
+                        webView: webView,
+                        duration: duration,
+                        curve: .linear
+                    )
+                }
+            }
+        }
+    }
+
+    /// Restores pre-duck volume level after notification ends.
+    func restoreAudio(
+        webView: WKWebView?,
+        duration: TimeInterval = 0.5
+    ) {
+        guard let webView, self.isDucked else { return }
+
+        self.isDucked = false
+        let restoredVolume = self.preDuckVolume
+
+        AudioFaderService.shared.fadeIn(
+            webView: webView,
+            targetVolume: restoredVolume,
+            duration: duration,
+            curve: .logarithmic
+        )
+    }
+}

Sources/Kaset/Services/AudioFader.swift

@@ -0,0 +1,20 @@
+import Foundation
+import WebKit
+
+/// Audio fader service for smooth volume transitions in WKWebView playback.
+@MainActor
+final class AudioFader {
+    static let shared = AudioFader()
+
+    private init() {}
+
+    /// Fade out volume to zero over specified duration
+    func fadeOut(webView: WKWebView?, duration: TimeInterval, completion: @escaping @MainActor () -> Void) {
+        AudioFaderService.shared.fadeOut(webView: webView, duration: duration, curve: .logarithmic, completion: completion)
+    }
+
+    /// Fade in volume from zero to target over specified duration
+    func fadeIn(webView: WKWebView?, targetVolume: Double = 1.0, duration: TimeInterval, completion: (@MainActor () -> Void)? = nil) {
+        AudioFaderService.shared.fadeIn(webView: webView, targetVolume: targetVolume, duration: duration, curve: .logarithmic, completion: completion)
+    }
+}