Content
# Music Agent
A Swift 6 project containing libraries and tools for controlling your music ecosystem through both direct API access and Model Context Protocol (MCP) servers. The project includes an AI-powered command-line agent that leverages [AgentKit](https://github.com/sebsto/AgentKit) to create an intelligent music assistant for your home.
## Architecture
### Core Libraries
1. **AppleMusicKit**: A library for interacting with the Apple Music API
2. **SonosKit**: A library for controlling Sonos speakers through the node-sonos-http-api
3. **AmplifierKit**: A library for controlling Denon/Marantz amplifiers
4. **OpenURLKit**: A library for opening URLs in the default browser
5. **MusicPlayerControlTool**: A tool for controlling a simple web-based music player
### MCP Server Integration
Each kit exposes its functionality as MCP (Model Context Protocol) tools, allowing AI agents to interact with your music ecosystem. The **MusicMCPServer** executable combines all tools into a single MCP server that can be used by AI assistants.
### AI Agent
The **MusicAgentCLI** is an intelligent command-line assistant powered by AWS Bedrock and AgentKit that can:
- Search for music using natural language
- Control your home audio system
- Play music on various devices
- Answer questions about songs and artists
## Features
### AppleMusicKit
- Search the Apple Music catalog by artist name, song title, or both
- Get detailed information about specific songs
- Generate Apple Music API developer tokens using ES256 algorithm
- MCP tools for AI agent integration
- Command-line interface for testing
### SonosKit
- Control playback (play, pause, stop, next, previous)
- Manage queue (add tracks, clear queue)
- Set volume and shuffle modes
- Get player state and room information
- List available rooms/zones
- Play Apple Music songs, albums, and playlists
- Join/leave room groups
- MCP tools for AI agent integration
- Command-line interface for testing
### AmplifierKit
- Power on/off your amplifier
- Switch between input sources (Sonos, Apple TV, or by index)
- Get available source names with indices
- Get amplifier status
- SSL certificate bypass for local network devices
- MCP tools for AI agent integration
- Command-line interface for testing
### OpenURLKit
- Open URLs in the default browser
- Support for macOS and iOS platforms
- Error handling for invalid URLs
- MCP tools for AI agent integration
- Command-line interface for testing
### MusicPlayerControlTool
- Control a simple web-based music player
- Add/remove songs from play queue
- JSON-based command interface
- MCP tool for AI agent integration
## Requirements
- Swift 6.0+
- macOS 15.0+
- For AppleMusicKit: Apple Music API developer token
- For SonosKit: [node-sonos-http-api](https://github.com/jishi/node-sonos-http-api) running locally or on a network
- For AmplifierKit: Denon/Marantz amplifier on your local network
- For MusicAgentCLI: AWS credentials and [AgentKit](https://github.com/sebsto/AgentKit) dependency
## Installation
### Swift Package Manager
Add the following to your `Package.swift` file:
```swift
dependencies: [
.package(url: "https://github.com/sebsto/MusicAgentKit.git", from: "1.0.0"),
.package(url: "https://github.com/sebsto/AgentKit.git", from: "1.0.0") // Required for AI agent functionality
]
```
### Building the Project
```bash
# Clone the repository
git clone https://github.com/sebsto/MusicAgentKit.git
cd MusicAgentKit
# Build all targets
swift build
# Build specific executables
swift build --product MusicAgentCLI
swift build --product MusicMCPServer
```
## Usage
### MusicAgentCLI - AI Music Assistant
The AI-powered music assistant uses AWS Bedrock and AgentKit to provide natural language control of your music ecosystem:
```bash
# Start the interactive AI assistant
swift run MusicAgentCLI
# With specific AWS profile
swift run MusicAgentCLI --profile-name myprofile
# With SSO authentication
swift run MusicAgentCLI --sso
# With custom region
swift run MusicAgentCLI --region us-west-2
```
Example interactions:
- "What is the status of the amplifier?"
- "Play Bohemian Rhapsody by Queen"
- "What is the release date of Hotel California?"
- "Switch to Sonos input and play some jazz"
### MusicMCPServer - MCP Server (HTTP)
Run the MCP server to expose all music control tools over HTTP to AI assistants:
```bash
# Start the MCP server
swift run MusicMCPServer
```
The server exposes tools for:
- Amplifier control (power, source switching, status)
- Sonos control (playback, volume, queue management)
- Apple Music search and playback
- URL opening
- Music player control
### Library Usage
#### AppleMusicKit
```swift
import AppleMusicKit
// Initialize with an existing developer token
let client = AppleMusicClient(developerToken: "your_developer_token", storefront: "us")
// Or initialize with a Secret (private key, team ID, key ID)
let secret = Secret(privateKey: privateKeyString, teamId: "YOUR_TEAM_ID", keyId: "YOUR_KEY_ID")
let client = try await AppleMusicClient(secret: secret, storefront: "us")
// Search by artist
let artistResults = try await client.searchByArtist("Queen")
// Search by song title
let songResults = try await client.searchByTitle("Bohemian Rhapsody")
// Search by both artist and title
let combinedResults = try await client.searchByArtistAndTitle(artist: "Queen", title: "Bohemian Rhapsody")
// Get details for a specific song
let songDetails = try await client.getSongDetails(id: "1234567890")
// Generate a token directly
let tokenFactory = AppleMusicTokenFactory(secret: secret)
let token = try await tokenFactory.generateToken()
```
#### SonosKit
```swift
import SonosKit
// Initialize with default host and port
let client = SonosClient()
// Or initialize with custom host, port, and default room
let client = SonosClient(host: "192.168.1.100", port: 5005, defaultRoom: "Living Room")
// Control playback
try await client.play()
try await client.pause()
try await client.stop()
try await client.next()
try await client.previous()
// Set volume
try await client.setVolume(50)
// Manage queue
try await client.addToQueue(uri: "spotify:track:5hTpBe8h35rJ67eAWHQsJx")
try await client.clearQueue()
// Play Apple Music content
try await client.playAppleMusic(contentType: .song, contentId: "355364259", mode: .queue)
try await client.playAppleMusic(contentType: .album, contentId: "355363490", mode: .now)
try await client.playAppleMusic(contentType: .playlist, contentId: "pl.ed52c9eeaa0740079c21fa8e455b225e", mode: .next)
// Get state
let state = try await client.getState()
print("Now playing: \(state.currentTrack.title) by \(state.currentTrack.artist)")
// List rooms
let rooms = try await client.getRooms()
for room in rooms {
print(room)
}
```
#### AmplifierKit
```swift
import AmplifierKit
// Initialize with default host and port
let config = AmplifierConfig(host: "192.168.1.37", port: 10443)
let controller = HTTPAmplifierController(config: config)
// Power control
try await controller.powerOn()
try await controller.powerOff()
// Source control
try await controller.switchToSource(index: 4) // Switch to source with index 4
try await controller.switchToSonos() // Shortcut to switch to Sonos
try await controller.switchToAppleTV() // Shortcut to switch to Apple TV
// Get information
let sources = try await controller.getSourceNames()
let status = try await controller.getMainZoneStatus()
print("Zone: \(status.name), Power: \(status.isPowered ? "On" : "Off")")
```
#### OpenURLKit
```swift
import OpenURLKit
// Open a URL directly
try URLOpener.open("https://aws.amazon.com")
// Or with a URL object
let url = URL(string: "https://aws.amazon.com")!
try URLOpener.open(url)
// Error handling
do {
try URLOpener.open("invalid-url")
} catch URLOpenerError.invalidURL {
print("The URL is invalid")
} catch URLOpenerError.failedToOpenURL {
print("Failed to open the URL")
} catch {
print("An error occurred: \(error)")
}
```
## Command-Line Interfaces
### AppleMusicCLI Usage
```bash
# Search by artist (uses built-in token generation)
swift run AppleMusicCLI artist "Queen"
# Search by title (uses built-in token generation)
swift run AppleMusicCLI title "Bohemian Rhapsody"
# Search by both artist and title (uses built-in token generation)
swift run AppleMusicCLI search "Queen" "Bohemian Rhapsody"
# Get song details (uses built-in token generation)
swift run AppleMusicCLI song "1234567890"
# Generate a token using the built-in ES256 implementation (default)
swift run AppleMusicCLI token
# Generate a token with custom credentials
swift run AppleMusicCLI token --team-id "YOUR_TEAM_ID" --key-id "YOUR_KEY_ID" --key-path "/path/to/private_key.p8"
```
### SonosCLI Usage
First, start the node-sonos-http-api server:
```bash
# Start the Sonos HTTP API server
./setup_sonos_api.sh
```
Then, in a new terminal window:
```bash
# Get the current state (default command)
swift run SonosCLI
# Play music
swift run SonosCLI play --room "Living Room"
# Pause music
swift run SonosCLI pause --room "Living Room"
# Set volume
swift run SonosCLI volume 50 --room "Living Room"
# Play Apple Music song now
swift run SonosCLI applemusic song "355364259" --mode now --room "Living Room"
# List available rooms
swift run SonosCLI rooms
```
### AmplifierCLI Usage
```bash
# Power on the amplifier
swift run AmplifierCLI power-on
# Power off the amplifier
swift run AmplifierCLI power-off
# Switch to Sonos input
swift run AmplifierCLI sonos
# Switch to Apple TV input
swift run AmplifierCLI appletv
# Switch to a specific source by index
swift run AmplifierCLI source 3
# List all available sources with their indices
swift run AmplifierCLI sources
# Get amplifier status
swift run AmplifierCLI status
```
### OpenURLCLI Usage
```bash
# Open a URL in the default browser
swift run OpenURLCLI open "https://aws.amazon.com"
# Or use the default subcommand
swift run OpenURLCLI "https://aws.amazon.com"
```
## Setup and Configuration
### Apple Music API Setup
To use the Apple Music API, you need to obtain developer credentials:
1. **Enroll in the Apple Developer Program**: If you haven't already, enroll at [developer.apple.com](https://developer.apple.com/).
2. **Create a MusicKit identifier**:
- Go to [Apple Developer Account](https://developer.apple.com/account/)
- Navigate to "Certificates, Identifiers & Profiles"
- Select "Identifiers" and click the "+" button
- Choose "Media IDs" and follow the instructions to register a MusicKit identifier
3. **Generate a private key**:
- In your Apple Developer Account, go to "Keys"
- Click the "+" button to add a new key
- Give it a name and select "MusicKit" checkbox
- Click "Continue" and then "Register"
- **IMPORTANT**: Download the private key file (.p8) when prompted. Apple only provides this file ONCE.
4. **Note your credentials**:
- **Team ID**: Found in the top-right corner of your Apple Developer Account page
- **Key ID**: The identifier for the key you just created
- **Private Key**: The contents of the .p8 file you downloaded
5. **Update the Secret.swift file**:
- Open `Sources/AppleMusicKit/DefaultSecret.swift`
- Uncomment the `defaultSecret` section
- Replace the placeholder values with your actual credentials:
```swift
public let defaultSecret = Secret(
privateKey: """
-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_CONTENT_HERE
-----END PRIVATE KEY-----
""",
teamId: "YOUR_TEAM_ID",
keyId: "YOUR_KEY_ID"
)
```
For more information, see [Apple's documentation on generating developer tokens](https://developer.apple.com/documentation/applemusicapi/generating-developer-tokens).
### AWS Credentials Setup
For the AI agent functionality, you need AWS credentials:
1. **Install AWS CLI** and configure your credentials:
```bash
aws configure
```
2. **Or use AWS SSO**:
```bash
aws sso login --profile myprofile
```
3. **Or use temporary credentials** by providing a path to a credentials file.
### MCP Configuration
The MCP server configuration is stored in `mcp-stdio.json`. Update the path to match your build location:
```json
{
"mcpServers": {
"MusicMCPServer": {
"command": "/path/to/your/.build/debug/MusicMCPServer",
"args": []
}
}
}
```
### Sonos Control Setup
1. Install and run the [node-sonos-http-api](https://github.com/jishi/node-sonos-http-api):
```bash
git clone https://github.com/jishi/node-sonos-http-api.git
cd node-sonos-http-api
npm install
npm start
```
2. The API will automatically discover your Sonos speakers on the network.
3. Update the SonosClient configuration with the host and port where the API is running:
```swift
let client = SonosClient(host: "192.168.1.100", port: 5005)
```
### Amplifier Control Setup
1. Ensure your Denon/Marantz amplifier is connected to your local network.
2. Find the IP address of your amplifier (check your router's DHCP client list or the amplifier's network settings).
3. Update the AmplifierConfig with the correct IP address:
```swift
let config = AmplifierConfig(host: "192.168.1.37", port: 10443)
```
4. The AmplifierKit includes SSL certificate bypass functionality for dealing with self-signed certificates commonly used by these devices.
## Project Structure
```
MusicAgent/
├── Sources/
│ ├── AmplifierKit/ # Amplifier control library + MCP tools
│ ├── AmplifierCLI/ # Command-line interface for amplifier
│ ├── AppleMusicKit/ # Apple Music API library + MCP tools
│ ├── AppleMusicCLI/ # Command-line interface for Apple Music
│ ├── SonosKit/ # Sonos control library + MCP tools
│ ├── SonosCLI/ # Command-line interface for Sonos
│ ├── OpenURLKit/ # URL opening library + MCP tools
│ ├── OpenURLCLI/ # Command-line interface for URL opening
│ ├── MusicPlayerControlTool/ # Web player control tool
│ ├── MusicMCPServer/ # Combined MCP server for all tools
│ └── MusicAgentCLI/ # AI-powered music assistant
├── Tests/ # Unit tests for all libraries
├── web_player/ # Simple web-based music player
├── sonos-api/ # Node.js Sonos HTTP API
└── data/ # Sample MCP call data
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Connection Info
You Might Also Like
No recommendations available