coder-music-cli 0.3.0__tar.gz → 0.4.1__tar.gz

{coder_music_cli-0.3.0 → coder_music_cli-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coder-music-cli
-Version: 0.3.0
+Version: 0.4.1
 Summary: A command-line music application for coders with daemon support, radio streaming, and AI-generated music
 Author-email: Luong Nguyen <luongnv89@gmail.com>
 Maintainer-email: Luong Nguyen <luongnv89@gmail.com>
@@ -16,6 +16,7 @@ Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -43,11 +44,21 @@ Requires-Dist: bandit>=1.7; extra == "dev"
 Requires-Dist: pre-commit>=3.0; extra == "dev"
 Dynamic: license-file
 
-# music-cli
+<p align="center">
+  <img src="assets/logo/logo-mark.svg" alt="music-cli logo" width="80" height="80">
+</p>
+
+<h1 align="center">music-cli</h1>
 
-[![PyPI version](https://img.shields.io/pypi/v/coder-music-cli.svg)](https://pypi.org/project/coder-music-cli/)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<p align="center">
+  <a href="https://pypi.org/project/coder-music-cli/"><img src="https://img.shields.io/pypi/v/coder-music-cli.svg" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <img src="music-cli-ai.gif" alt="music-cli AI demo" width="600">
+</p>
 
 A command-line music player for coders. Background daemon with radio streaming, local MP3s, and AI-generated music.
 
@@ -68,8 +79,9 @@ pip install coder-music-cli
 uv pip install coder-music-cli
 
 # Install FFmpeg (required)
-brew install ffmpeg      # macOS
-sudo apt install ffmpeg  # Ubuntu/Debian
+brew install ffmpeg       # macOS
+sudo apt install ffmpeg   # Ubuntu/Debian
+choco install ffmpeg      # Windows (or: winget install ffmpeg)
 ```
 
 ### Optional: AI Music Generation
@@ -116,6 +128,7 @@ music-cli radios add              # Add new station
 | `next` | Skip track (auto-play mode) |
 | `volume [0-100]` | Get/set volume |
 | `radios` | Manage radio stations (list/play/add/remove) |
+| `ai` | Manage AI-generated tracks (list/play/replay/remove) |
 | `history` | Playback log |
 | `moods` | Available mood tags |
 | `config` | Show configuration file locations |
@@ -175,16 +188,35 @@ Generate unique music with Meta's MusicGen model:
 # Install AI dependencies
 pip install 'coder-music-cli[ai]'
 
-# Generate music
-music-cli play -m ai --mood focus -d 30   # 30-second focus track
-music-cli play -m ai --mood energetic     # Energetic music
+# Generate and manage AI music
+music-cli ai play                         # Context-aware generation
+music-cli ai play -p "jazz piano"         # Custom prompt
+music-cli ai play --mood focus -d 30      # 30-second focus track
+music-cli ai list                         # List all generated tracks
+music-cli ai replay 1                     # Replay track #1
+music-cli ai remove 2                     # Delete track #2
 ```
 
+### AI Command Suite
+
+| Command | Description |
+|---------|-------------|
+| `ai list` | Show all AI-generated tracks with prompts |
+| `ai play` | Generate music from current context |
+| `ai play -p "prompt"` | Generate with custom prompt |
+| `ai play --mood focus` | Generate with specific mood |
+| `ai play -d 30` | Generate 30-second track (default: 5s) |
+| `ai replay <num>` | Replay track by number (regenerates if file missing) |
+| `ai remove <num>` | Delete track and audio file |
+
 Features:
+- **Context-aware** - Uses time of day, day of week, and session mood
+- **Custom prompts** - Generate exactly what you want with `-p`
+- **Seamless looping** - All tracks engineered for infinite playback
+- **Track management** - List, replay, and remove generated tracks
+- **Regeneration** - Missing files can be regenerated with original prompt
 - **Animated feedback** - "composing..." animation while generating
-- **Persistent storage** - Generated tracks saved to `~/.config/music-cli/ai_music/`
-- **Replay support** - AI tracks appear in history for replay
-- **Auto-loop** - Generated tracks loop automatically
+- **Persistent storage** - Tracks saved to `~/.config/music-cli/ai_music/`
 
 ## Moods
 
@@ -192,14 +224,17 @@ Features:
 
 ## Configuration
 
-Files in `~/.config/music-cli/`:
+Configuration files location:
+- **Linux/macOS**: `~/.config/music-cli/`
+- **Windows**: `%LOCALAPPDATA%\music-cli\`
 
 | File | Purpose |
 |------|---------|
 | `config.toml` | Settings (volume, mood mappings, version) |
 | `radios.txt` | Station URLs (name\|url format) |
 | `history.jsonl` | Play history |
-| `ai_music/` | AI-generated tracks |
+| `ai_tracks.json` | AI track metadata (prompts, durations) |
+| `ai_music/` | AI-generated audio files |
 
 ### Version Updates
 
@@ -255,9 +290,28 @@ GitHub: https://github.com/luongnv89/music-cli
 
 - Python 3.9+
 - FFmpeg
+- **Supported Platforms**: Linux, macOS, Windows 10+
 
 ## Changelog
 
+### v0.4.1
+- Add Windows 10+ support
+  - Platform abstraction layer for cross-platform compatibility
+  - TCP localhost IPC on Windows (Unix sockets on Linux/macOS)
+  - stdin-based pause/resume on Windows (signals on Linux/macOS)
+  - Windows-specific config directory (`%LOCALAPPDATA%\music-cli\`)
+- Add Windows to CI test matrix
+
+### v0.4.0
+- Add `music-cli ai` command suite for AI track management
+  - `ai list` - Display all AI tracks with prompts
+  - `ai play [-p "prompt"]` - Generate with context or custom prompt
+  - `ai replay <num>` - Replay track (regenerates if missing)
+  - `ai remove <num>` - Delete track and audio file
+- Add seamless looping via prompt engineering
+- Add context-aware AI generation (time of day, day of week, mood)
+- Default AI duration reduced to 5s for faster generation
+
 ### v0.3.0
 - Add radio station management (list/play/add/remove by number)
 - Add 35 curated radio stations (English, French, Spanish, Italian)

{coder_music_cli-0.3.0 → coder_music_cli-0.4.1}/README.md

@@ -1,8 +1,18 @@
-# music-cli
+<p align="center">
+  <img src="assets/logo/logo-mark.svg" alt="music-cli logo" width="80" height="80">
+</p>
 
-[![PyPI version](https://img.shields.io/pypi/v/coder-music-cli.svg)](https://pypi.org/project/coder-music-cli/)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<h1 align="center">music-cli</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/coder-music-cli/"><img src="https://img.shields.io/pypi/v/coder-music-cli.svg" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <img src="music-cli-ai.gif" alt="music-cli AI demo" width="600">
+</p>
 
 A command-line music player for coders. Background daemon with radio streaming, local MP3s, and AI-generated music.
 
@@ -23,8 +33,9 @@ pip install coder-music-cli
 uv pip install coder-music-cli
 
 # Install FFmpeg (required)
-brew install ffmpeg      # macOS
-sudo apt install ffmpeg  # Ubuntu/Debian
+brew install ffmpeg       # macOS
+sudo apt install ffmpeg   # Ubuntu/Debian
+choco install ffmpeg      # Windows (or: winget install ffmpeg)
 ```
 
 ### Optional: AI Music Generation
@@ -71,6 +82,7 @@ music-cli radios add              # Add new station
 | `next` | Skip track (auto-play mode) |
 | `volume [0-100]` | Get/set volume |
 | `radios` | Manage radio stations (list/play/add/remove) |
+| `ai` | Manage AI-generated tracks (list/play/replay/remove) |
 | `history` | Playback log |
 | `moods` | Available mood tags |
 | `config` | Show configuration file locations |
@@ -130,16 +142,35 @@ Generate unique music with Meta's MusicGen model:
 # Install AI dependencies
 pip install 'coder-music-cli[ai]'
 
-# Generate music
-music-cli play -m ai --mood focus -d 30   # 30-second focus track
-music-cli play -m ai --mood energetic     # Energetic music
+# Generate and manage AI music
+music-cli ai play                         # Context-aware generation
+music-cli ai play -p "jazz piano"         # Custom prompt
+music-cli ai play --mood focus -d 30      # 30-second focus track
+music-cli ai list                         # List all generated tracks
+music-cli ai replay 1                     # Replay track #1
+music-cli ai remove 2                     # Delete track #2
 ```
 
+### AI Command Suite
+
+| Command | Description |
+|---------|-------------|
+| `ai list` | Show all AI-generated tracks with prompts |
+| `ai play` | Generate music from current context |
+| `ai play -p "prompt"` | Generate with custom prompt |
+| `ai play --mood focus` | Generate with specific mood |
+| `ai play -d 30` | Generate 30-second track (default: 5s) |
+| `ai replay <num>` | Replay track by number (regenerates if file missing) |
+| `ai remove <num>` | Delete track and audio file |
+
 Features:
+- **Context-aware** - Uses time of day, day of week, and session mood
+- **Custom prompts** - Generate exactly what you want with `-p`
+- **Seamless looping** - All tracks engineered for infinite playback
+- **Track management** - List, replay, and remove generated tracks
+- **Regeneration** - Missing files can be regenerated with original prompt
 - **Animated feedback** - "composing..." animation while generating
-- **Persistent storage** - Generated tracks saved to `~/.config/music-cli/ai_music/`
-- **Replay support** - AI tracks appear in history for replay
-- **Auto-loop** - Generated tracks loop automatically
+- **Persistent storage** - Tracks saved to `~/.config/music-cli/ai_music/`
 
 ## Moods
 
@@ -147,14 +178,17 @@ Features:
 
 ## Configuration
 
-Files in `~/.config/music-cli/`:
+Configuration files location:
+- **Linux/macOS**: `~/.config/music-cli/`
+- **Windows**: `%LOCALAPPDATA%\music-cli\`
 
 | File | Purpose |
 |------|---------|
 | `config.toml` | Settings (volume, mood mappings, version) |
 | `radios.txt` | Station URLs (name\|url format) |
 | `history.jsonl` | Play history |
-| `ai_music/` | AI-generated tracks |
+| `ai_tracks.json` | AI track metadata (prompts, durations) |
+| `ai_music/` | AI-generated audio files |
 
 ### Version Updates
 
@@ -210,9 +244,28 @@ GitHub: https://github.com/luongnv89/music-cli
 
 - Python 3.9+
 - FFmpeg
+- **Supported Platforms**: Linux, macOS, Windows 10+
 
 ## Changelog
 
+### v0.4.1
+- Add Windows 10+ support
+  - Platform abstraction layer for cross-platform compatibility
+  - TCP localhost IPC on Windows (Unix sockets on Linux/macOS)
+  - stdin-based pause/resume on Windows (signals on Linux/macOS)
+  - Windows-specific config directory (`%LOCALAPPDATA%\music-cli\`)
+- Add Windows to CI test matrix
+
+### v0.4.0
+- Add `music-cli ai` command suite for AI track management
+  - `ai list` - Display all AI tracks with prompts
+  - `ai play [-p "prompt"]` - Generate with context or custom prompt
+  - `ai replay <num>` - Replay track (regenerates if missing)
+  - `ai remove <num>` - Delete track and audio file
+- Add seamless looping via prompt engineering
+- Add context-aware AI generation (time of day, day of week, mood)
+- Default AI duration reduced to 5s for faster generation
+
 ### v0.3.0
 - Add radio station management (list/play/add/remove by number)
 - Add 35 curated radio stations (English, French, Spanish, Italian)

{coder_music_cli-0.3.0 → coder_music_cli-0.4.1}/coder_music_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coder-music-cli
-Version: 0.3.0
+Version: 0.4.1
 Summary: A command-line music application for coders with daemon support, radio streaming, and AI-generated music
 Author-email: Luong Nguyen <luongnv89@gmail.com>
 Maintainer-email: Luong Nguyen <luongnv89@gmail.com>
@@ -16,6 +16,7 @@ Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -43,11 +44,21 @@ Requires-Dist: bandit>=1.7; extra == "dev"
 Requires-Dist: pre-commit>=3.0; extra == "dev"
 Dynamic: license-file
 
-# music-cli
+<p align="center">
+  <img src="assets/logo/logo-mark.svg" alt="music-cli logo" width="80" height="80">
+</p>
+
+<h1 align="center">music-cli</h1>
 
-[![PyPI version](https://img.shields.io/pypi/v/coder-music-cli.svg)](https://pypi.org/project/coder-music-cli/)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<p align="center">
+  <a href="https://pypi.org/project/coder-music-cli/"><img src="https://img.shields.io/pypi/v/coder-music-cli.svg" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <img src="music-cli-ai.gif" alt="music-cli AI demo" width="600">
+</p>
 
 A command-line music player for coders. Background daemon with radio streaming, local MP3s, and AI-generated music.
 
@@ -68,8 +79,9 @@ pip install coder-music-cli
 uv pip install coder-music-cli
 
 # Install FFmpeg (required)
-brew install ffmpeg      # macOS
-sudo apt install ffmpeg  # Ubuntu/Debian
+brew install ffmpeg       # macOS
+sudo apt install ffmpeg   # Ubuntu/Debian
+choco install ffmpeg      # Windows (or: winget install ffmpeg)
 ```
 
 ### Optional: AI Music Generation
@@ -116,6 +128,7 @@ music-cli radios add              # Add new station
 | `next` | Skip track (auto-play mode) |
 | `volume [0-100]` | Get/set volume |
 | `radios` | Manage radio stations (list/play/add/remove) |
+| `ai` | Manage AI-generated tracks (list/play/replay/remove) |
 | `history` | Playback log |
 | `moods` | Available mood tags |
 | `config` | Show configuration file locations |
@@ -175,16 +188,35 @@ Generate unique music with Meta's MusicGen model:
 # Install AI dependencies
 pip install 'coder-music-cli[ai]'
 
-# Generate music
-music-cli play -m ai --mood focus -d 30   # 30-second focus track
-music-cli play -m ai --mood energetic     # Energetic music
+# Generate and manage AI music
+music-cli ai play                         # Context-aware generation
+music-cli ai play -p "jazz piano"         # Custom prompt
+music-cli ai play --mood focus -d 30      # 30-second focus track
+music-cli ai list                         # List all generated tracks
+music-cli ai replay 1                     # Replay track #1
+music-cli ai remove 2                     # Delete track #2
 ```
 
+### AI Command Suite
+
+| Command | Description |
+|---------|-------------|
+| `ai list` | Show all AI-generated tracks with prompts |
+| `ai play` | Generate music from current context |
+| `ai play -p "prompt"` | Generate with custom prompt |
+| `ai play --mood focus` | Generate with specific mood |
+| `ai play -d 30` | Generate 30-second track (default: 5s) |
+| `ai replay <num>` | Replay track by number (regenerates if file missing) |
+| `ai remove <num>` | Delete track and audio file |
+
 Features:
+- **Context-aware** - Uses time of day, day of week, and session mood
+- **Custom prompts** - Generate exactly what you want with `-p`
+- **Seamless looping** - All tracks engineered for infinite playback
+- **Track management** - List, replay, and remove generated tracks
+- **Regeneration** - Missing files can be regenerated with original prompt
 - **Animated feedback** - "composing..." animation while generating
-- **Persistent storage** - Generated tracks saved to `~/.config/music-cli/ai_music/`
-- **Replay support** - AI tracks appear in history for replay
-- **Auto-loop** - Generated tracks loop automatically
+- **Persistent storage** - Tracks saved to `~/.config/music-cli/ai_music/`
 
 ## Moods
 
@@ -192,14 +224,17 @@ Features:
 
 ## Configuration
 
-Files in `~/.config/music-cli/`:
+Configuration files location:
+- **Linux/macOS**: `~/.config/music-cli/`
+- **Windows**: `%LOCALAPPDATA%\music-cli\`
 
 | File | Purpose |
 |------|---------|
 | `config.toml` | Settings (volume, mood mappings, version) |
 | `radios.txt` | Station URLs (name\|url format) |
 | `history.jsonl` | Play history |
-| `ai_music/` | AI-generated tracks |
+| `ai_tracks.json` | AI track metadata (prompts, durations) |
+| `ai_music/` | AI-generated audio files |
 
 ### Version Updates
 
@@ -255,9 +290,28 @@ GitHub: https://github.com/luongnv89/music-cli
 
 - Python 3.9+
 - FFmpeg
+- **Supported Platforms**: Linux, macOS, Windows 10+
 
 ## Changelog
 
+### v0.4.1
+- Add Windows 10+ support
+  - Platform abstraction layer for cross-platform compatibility
+  - TCP localhost IPC on Windows (Unix sockets on Linux/macOS)
+  - stdin-based pause/resume on Windows (signals on Linux/macOS)
+  - Windows-specific config directory (`%LOCALAPPDATA%\music-cli\`)
+- Add Windows to CI test matrix
+
+### v0.4.0
+- Add `music-cli ai` command suite for AI track management
+  - `ai list` - Display all AI tracks with prompts
+  - `ai play [-p "prompt"]` - Generate with context or custom prompt
+  - `ai replay <num>` - Replay track (regenerates if missing)
+  - `ai remove <num>` - Delete track and audio file
+- Add seamless looping via prompt engineering
+- Add context-aware AI generation (time of day, day of week, mood)
+- Default AI duration reduced to 5s for faster generation
+
 ### v0.3.0
 - Add radio station management (list/play/add/remove by number)
 - Add 35 curated radio stations (English, French, Spanish, Italian)

{coder_music_cli-0.3.0 → coder_music_cli-0.4.1}/coder_music_cli.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ coder_music_cli.egg-info/requires.txt
 coder_music_cli.egg-info/top_level.txt
 music_cli/__init__.py
 music_cli/__main__.py
+music_cli/ai_tracks.py
 music_cli/cli.py
 music_cli/client.py
 music_cli/config.py
@@ -17,6 +18,10 @@ music_cli/history.py
 music_cli/context/__init__.py
 music_cli/context/mood.py
 music_cli/context/temporal.py
+music_cli/platform/__init__.py
+music_cli/platform/ipc.py
+music_cli/platform/paths.py
+music_cli/platform/player_control.py
 music_cli/player/__init__.py
 music_cli/player/base.py
 music_cli/player/ffplay.py
@@ -24,6 +29,7 @@ music_cli/sources/__init__.py
 music_cli/sources/ai_generator.py
 music_cli/sources/local.py
 music_cli/sources/radio.py
+tests/test_ai_tracks.py
 tests/test_config.py
 tests/test_context.py
 tests/test_history.py

{coder_music_cli-0.3.0 → coder_music_cli-0.4.1}/music_cli/__init__.py

@@ -1,4 +1,4 @@
 """music-cli: A command-line music application for coders."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.1"
 __github_url__ = "https://github.com/luongnv89/music-cli"

coder_music_cli-0.4.1/music_cli/ai_tracks.py

@@ -0,0 +1,216 @@
+"""AI track management for music-cli."""
+
+import json
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from .config import get_config
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AITrack:
+    """A single AI-generated track entry."""
+
+    prompt: str
+    file_path: str
+    timestamp: str
+    duration: int
+    model: str = "musicgen-small"
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "prompt": self.prompt,
+            "file_path": self.file_path,
+            "timestamp": self.timestamp,
+            "duration": self.duration,
+            "model": self.model,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AITrack":
+        """Create from dictionary."""
+        return cls(
+            prompt=data.get("prompt", ""),
+            file_path=data.get("file_path", ""),
+            timestamp=data.get("timestamp", ""),
+            duration=data.get("duration", 30),
+            model=data.get("model", "musicgen-small"),
+        )
+
+    def file_exists(self) -> bool:
+        """Check if the audio file still exists."""
+        return Path(self.file_path).exists()
+
+    def display_prompt(self, max_length: int = 50) -> str:
+        """Get a truncated prompt for display."""
+        if len(self.prompt) <= max_length:
+            return self.prompt
+        return self.prompt[: max_length - 3] + "..."
+
+
+class AITracksManager:
+    """Manages AI-generated tracks storage and retrieval."""
+
+    def __init__(self, tracks_file: Path | None = None):
+        """Initialize AI tracks manager.
+
+        Args:
+            tracks_file: Path to the ai_tracks.json file.
+                        Defaults to config directory.
+        """
+        if tracks_file is None:
+            tracks_file = get_config().ai_tracks_file
+        self.tracks_file = tracks_file
+        self._ensure_file()
+
+    def _ensure_file(self) -> None:
+        """Create the tracks file if it doesn't exist."""
+        if not self.tracks_file.exists():
+            self.tracks_file.write_text("[]")
+
+    def _load_tracks(self) -> list[AITrack]:
+        """Load tracks from JSON file."""
+        try:
+            data = json.loads(self.tracks_file.read_text())
+            return [AITrack.from_dict(item) for item in data]
+        except (json.JSONDecodeError, OSError) as e:
+            logger.warning(f"Failed to load AI tracks: {e}")
+            return []
+
+    def _save_tracks(self, tracks: list[AITrack]) -> None:
+        """Save tracks to JSON file."""
+        data = [track.to_dict() for track in tracks]
+        self.tracks_file.write_text(json.dumps(data, indent=2))
+
+    def get_all(self) -> list[AITrack]:
+        """Get all AI tracks.
+
+        Returns tracks in reverse chronological order (newest first).
+        """
+        tracks = self._load_tracks()
+        tracks.reverse()
+        return tracks
+
+    def add_track(
+        self,
+        prompt: str,
+        file_path: str,
+        duration: int,
+        model: str = "musicgen-small",
+    ) -> AITrack:
+        """Add a new AI track.
+
+        Args:
+            prompt: The prompt used for generation.
+            file_path: Path to the generated audio file.
+            duration: Duration in seconds.
+            model: Model name used for generation.
+
+        Returns:
+            The newly created AITrack.
+        """
+        track = AITrack(
+            prompt=prompt,
+            file_path=file_path,
+            timestamp=datetime.now().isoformat(),
+            duration=duration,
+            model=model,
+        )
+
+        tracks = self._load_tracks()
+        tracks.append(track)
+        self._save_tracks(tracks)
+
+        return track
+
+    def get_by_index(self, index: int) -> AITrack | None:
+        """Get a track by its 1-based index (newest first).
+
+        Args:
+            index: 1-based index of the track.
+
+        Returns:
+            AITrack if found, None otherwise.
+        """
+        tracks = self.get_all()
+        if 1 <= index <= len(tracks):
+            return tracks[index - 1]
+        return None
+
+    def remove_by_index(self, index: int) -> AITrack | None:
+        """Remove a track by its 1-based index (newest first).
+
+        Also deletes the associated audio file.
+
+        Args:
+            index: 1-based index of the track.
+
+        Returns:
+            The removed AITrack if found, None otherwise.
+        """
+        tracks = self.get_all()
+        if not (1 <= index <= len(tracks)):
+            return None
+
+        removed = tracks[index - 1]
+
+        # Delete the audio file if it exists
+        file_path = Path(removed.file_path)
+        if file_path.exists():
+            try:
+                file_path.unlink()
+                logger.info(f"Deleted audio file: {file_path}")
+            except OSError as e:
+                logger.warning(f"Failed to delete audio file: {e}")
+
+        # Remove from list and save
+        # Note: tracks is reversed, so we need to work with original order
+        original_tracks = self._load_tracks()
+        # Index in original order (0-based from end)
+        original_index = len(original_tracks) - index
+        del original_tracks[original_index]
+        self._save_tracks(original_tracks)
+
+        return removed
+
+    def update_file_path(self, index: int, new_file_path: str) -> bool:
+        """Update the file path for a track (used after regeneration).
+
+        Args:
+            index: 1-based index of the track.
+            new_file_path: New path to the audio file.
+
+        Returns:
+            True if updated, False if track not found.
+        """
+        tracks = self._load_tracks()
+        # Convert to reversed index
+        reversed_index = len(tracks) - index
+        if not (0 <= reversed_index < len(tracks)):
+            return False
+
+        tracks[reversed_index].file_path = new_file_path
+        tracks[reversed_index].timestamp = datetime.now().isoformat()
+        self._save_tracks(tracks)
+        return True
+
+    def count(self) -> int:
+        """Get the total number of AI tracks."""
+        return len(self._load_tracks())
+
+
+# Global AI tracks manager instance
+_ai_tracks: AITracksManager | None = None
+
+
+def get_ai_tracks() -> AITracksManager:
+    """Get the global AI tracks manager instance."""
+    global _ai_tracks
+    if _ai_tracks is None:
+        _ai_tracks = AITracksManager()
+    return _ai_tracks