Skip to content

Commit 8449f32

Browse files
authored
Revise README for AI providers and scheduling updates
Updated README to reflect changes in AI integration and playlist scheduling.
1 parent f71160f commit 8449f32

1 file changed

Lines changed: 17 additions & 75 deletions

File tree

README.md

Lines changed: 17 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[![Docker Pulls](https://img.shields.io/docker/pulls/blueion76/octogen?logo=docker)](https://hub.docker.com/r/blueion76/octogen)
44

5-
**OctoGen** automatically generates personalized music playlists for your Navidrome server using AI. It creates 11 curated playlists with over 350 songs, seamlessly integrating with [Octo-Fiesta](https://github.com/V1ck3s/octo-fiesta) to download missing tracks.
5+
**OctoGen** automatically generates personalized music playlists for your Navidrome server using an LLM, LastFM, ListenBrainz or AudioMuse-AI seamlessly integrating with [Octo-Fiesta](https://github.com/V1ck3s/octo-fiesta) to download missing tracks.
66

77
Built with AI assistance. Contributions and pull requests welcome!
88

@@ -11,7 +11,7 @@ Built with AI assistance. Contributions and pull requests welcome!
1111
## ✨ Features
1212

1313
### 🤖 AI-Powered Recommendations
14-
- **Multiple AI providers**: Gemini, OpenAI, Groq, Ollama, OpenRouter
14+
- **Multiple AI providers**: Gemini and OpenAI-compatible API-supported providers
1515
- **Smart context caching**: Efficient, low-cost API usage
1616
- **Variety seed**: Different recommendations every day
1717

@@ -31,9 +31,9 @@ Built with AI assistance. Contributions and pull requests welcome!
3131
Automatic mood-appropriate playlists that rotate based on time of day:
3232

3333
- **Morning Mix (6 AM - 12 PM)**: Upbeat, energetic, positive vibes
34-
- **Afternoon Flow (12 PM - 6 PM)**: Balanced, productive, moderate energy
35-
- **Evening Chill (6 PM - 12 AM)**: Relaxing, wind-down music
36-
- **Night Vibes (12 AM - 6 AM)**: Ambient, calm, sleep-friendly
34+
- **Afternoon Flow (12 PM - 4 PM)**: Balanced, productive, moderate energy
35+
- **Evening Chill (4 PM - 10 PM)**: Relaxing, wind-down music
36+
- **Night Vibes (10 AM - 6 AM)**: Ambient, calm, sleep-friendly
3737

3838
**Features**:
3939
- ✅ Hybrid generation: 25 songs from AudioMuse-AI + 5 from LLM
@@ -83,16 +83,15 @@ See [AudioMuse-AI Setup](#-audiomuse-ai-setup-optional) below.
8383
- **Automatic downloads**: Missing songs fetched via Octo-Fiesta
8484
- **Daily cache**: Efficient library scanning
8585
- **Async operations**: Fast, parallel processing
86-
- **Last.fm & ListenBrainz**: Optional integration
86+
- **LastFM, ListenBrainz & AudioMuse-AI**: Optional integrations
8787
- **Built-in scheduling**: No external cron needed 🕐
8888

8989
### 📊 Monitoring & Observability
9090
- **Web UI dashboard**: Real-time service health monitoring with auto-refresh
9191
- **Prometheus metrics**: Track playlists, downloads, API calls, latency
92-
- **Swagger API docs**: Interactive REST API documentation at `/apidocs/`
9392
- **Circuit breaker**: Prevents cascading failures to external APIs
9493
- **Structured logging**: JSON format support for log aggregation
95-
- **Health checks**: Monitor Navidrome, Octo-Fiesta, AI, AudioMuse, Last.fm, ListenBrainz
94+
- **Health checks**: Monitor Navidrome, Octo-Fiesta, AI, AudioMuse, LastFM, ListenBrainz
9695

9796
### ⚙️ Advanced Features
9897
- **Modular architecture**: Clean, maintainable codebase
@@ -112,7 +111,7 @@ See [AudioMuse-AI Setup](#-audiomuse-ai-setup-optional) below.
112111
- **At least one music source**:
113112
- AI API key (Gemini recommended - free tier available), OR
114113
- AudioMuse-AI configured, OR
115-
- Last.fm enabled, OR
114+
- LastFM enabled, OR
116115
- ListenBrainz enabled
117116

118117
### 1. Get API Key (Optional - if using LLM)
@@ -162,18 +161,10 @@ docker logs -f octogen
162161
### 4. Check Your Navidrome
163162
Open Navidrome and find your new playlists! 🎉
164163

165-
**Playlists update automatically at 2 AM daily!**
164+
**Playlists update automatically at the time(s) you set your cronjob**
166165

167166
---
168167

169-
## 🐳 Docker Tags
170-
171-
OctoGen uses automated CI/CD to build and publish Docker images:
172-
173-
- **`dev`** - Automatically built from latest main branch (bleeding edge, may be unstable)
174-
- **`latest`** - Manually published stable releases (recommended for production)
175-
- **`sha-XXXXXXX`** - Build from specific commit (for debugging)
176-
177168

178169
### Using Development Builds
179170

@@ -210,7 +201,7 @@ services:
210201
AI_API_KEY: ${GEMINI_API_KEY}
211202

212203
# Scheduling
213-
SCHEDULE_CRON: "0 2 * * *" # Daily at 2 AM
204+
SCHEDULE_CRON: "0 2,6,12,16,22 * * *" # Daily at 2 AM, 6 AM, 12 PM, 4 PM and 10 PM
214205
TZ: America/Chicago
215206

216207
# Optional
@@ -241,7 +232,7 @@ OctoGen includes a real-time monitoring dashboard accessible at `http://localhos
241232
- Octo-Fiesta (connection status)
242233
- AI Engine (backend, model, status)
243234
- AudioMuse-AI (enabled/disabled, health)
244-
- Last.fm (enabled/disabled, connection)
235+
- LastFM (enabled/disabled, connection)
245236
- ListenBrainz (enabled/disabled, connection)
246237

247238
- **System Statistics**:
@@ -252,7 +243,7 @@ OctoGen includes a real-time monitoring dashboard accessible at `http://localhos
252243
- Last run timestamp
253244
- Next scheduled run
254245

255-
- **REST API**: Full API with Swagger documentation at `/apidocs/`
246+
- **REST API**:
256247
- `GET /api/health` - Overall health status
257248
- `GET /api/services` - Detailed service information
258249
- `GET /api/stats` - System statistics
@@ -297,21 +288,6 @@ To enable hybrid playlist generation with sonic analysis:
297288

298289
Follow the [AudioMuse-AI documentation](https://github.com/NeptuneHub/AudioMuse-AI) to deploy:
299290

300-
```yaml
301-
# docker-compose.yml excerpt
302-
services:
303-
audiomuse-flask:
304-
image: ghcr.io/neptunehub/audiomuse-ai:latest
305-
ports:
306-
- "8000:8000"
307-
environment:
308-
SERVICE_TYPE: "flask"
309-
MEDIASERVER_TYPE: "navidrome"
310-
NAVIDROME_URL: "http://navidrome:4533"
311-
NAVIDROME_USER: "admin"
312-
NAVIDROME_PASSWORD: "${NAVIDROME_PASSWORD}"
313-
# ... other AudioMuse config
314-
```
315291

316292
### 2. Run Initial Analysis
317293

@@ -339,8 +315,6 @@ AUDIOMUSE_SONGS_PER_MIX=25 # Songs from AudioMuse (default: 25)
339315
LLM_SONGS_PER_MIX=5 # Songs from LLM (default: 5)
340316
```
341317

342-
**Note:** Total songs per daily mix remains 30.
343-
344318
---
345319

346320
## 🔧 Configuration
@@ -357,7 +331,7 @@ LLM_SONGS_PER_MIX=5 # Songs from LLM (default: 5)
357331
**Note**: At least one music source must also be configured:
358332
- `AI_API_KEY` (for LLM-based playlists), OR
359333
- `AUDIOMUSE_ENABLED=true` (for AudioMuse-AI sonic analysis), OR
360-
- `LASTFM_ENABLED=true` (for Last.fm recommendations), OR
334+
- `LASTFM_ENABLED=true` (for LastFM recommendations), OR
361335
- `LISTENBRAINZ_ENABLED=true` (for ListenBrainz recommendations)
362336

363337
### Optional Configuration
@@ -421,7 +395,7 @@ AI_API_KEY=your_openrouter_api_key
421395

422396
## 🕐 Automatic Scheduling
423397

424-
OctoGen now includes **built-in cron scheduling** - no external cron daemon or scripts needed!
398+
OctoGen includes **built-in cron scheduling**
425399

426400
### Quick Setup
427401

@@ -492,38 +466,6 @@ TZ=Australia/Sydney # Australia
492466

493467
Leave `SCHEDULE_CRON` unset or set to `manual`:
494468

495-
```bash
496-
# Run once and exit
497-
docker run --rm --env-file .env blueion76/octogen:latest
498-
```
499-
500-
### Advanced: Kubernetes CronJob
501-
502-
If you prefer Kubernetes native scheduling:
503-
504-
```yaml
505-
apiVersion: batch/v1
506-
kind: CronJob
507-
metadata:
508-
name: octogen
509-
spec:
510-
schedule: "0 2 * * *"
511-
timeZone: "America/Chicago" # Kubernetes 1.25+
512-
jobTemplate:
513-
spec:
514-
template:
515-
spec:
516-
containers:
517-
- name: octogen
518-
image: blueion76/octogen:latest
519-
envFrom:
520-
- secretRef:
521-
name: octogen-secrets
522-
restartPolicy: OnFailure
523-
```
524-
525-
**Note:** Built-in scheduling is recommended for simplicity!
526-
527469
---
528470

529471
## 📊 How It Works
@@ -534,7 +476,7 @@ OctoGen uses a modular architecture with clean separation of concerns:
534476

535477
```
536478
octogen/
537-
├── api/ # External API clients (Navidrome, Last.fm, ListenBrainz, AudioMuse)
479+
├── api/ # External API clients (Navidrome, LastFM, ListenBrainz, AudioMuse)
538480
├── ai/ # Multi-backend AI recommendation engine
539481
├── monitoring/ # Prometheus metrics + circuit breaker
540482
├── web/ # Flask dashboard
@@ -553,7 +495,7 @@ octogen/
553495
- Caches ratings (daily refresh for performance)
554496

555497
2. **Generates AI recommendations**
556-
- Sends music profile to AI (or uses AudioMuse/Last.fm/ListenBrainz)
498+
- Sends music profile to AI (or uses AudioMuse/LastFM/ListenBrainz)
557499
- Excludes low-rated songs (1-2 stars)
558500
- Requests 11 themed playlists with variety
559501

@@ -821,7 +763,7 @@ Contributions welcome! Just create a pull request.
821763
- **[Navidrome](https://www.navidrome.org/)** - Open-source music server
822764
- **[Octo-Fiesta](https://github.com/V1ck3s/octo-fiesta)** - Automated music downloader
823765
- **[Google Gemini](https://ai.google.dev/)** - AI recommendations
824-
- **[Last.fm](https://www.last.fm/)** - Music discovery API
766+
- **[LastFM](https://www.LastFM/)** - Music discovery API
825767
- **[ListenBrainz](https://listenbrainz.org/)** - Open music metadata
826768
- **[AudioMuse-AI](https://github.com/NeptuneHub/AudioMuse-AI)** - In-depth analysis of your music library
827769

0 commit comments

Comments
 (0)