# Audiobookshelf

**🟢 Media Service**

## 📋 Service Overview

| Property | Value |
|----------|-------|
| **Service Name** | audiobookshelf |
| **Host** | Atlantis (Synology) |
| **Category** | Media / Books |
| **Difficulty** | 🟢 |
| **Docker Image** | `ghcr.io/advplyr/audiobookshelf:latest` |
| **Compose File** | `hosts/synology/atlantis/arr-suite/docker-compose.yml` |
| **Directory** | `hosts/synology/atlantis/arr-suite` |

## 🎯 Purpose

Audiobookshelf is a self-hosted audiobook and podcast server with mobile apps. Think of it as "Plex for audiobooks" - it provides a beautiful interface for browsing, streaming, and tracking progress across your audiobook and ebook library. It syncs progress across all devices and has native iOS/Android apps.

## 🚀 Quick Start

### Prerequisites
- Docker and Docker Compose installed
- Audiobooks/ebooks/podcasts organized in folders
- Access to the host system (Atlantis)

### Deployment
```bash
# Navigate to service directory
cd hosts/synology/atlantis/arr-suite

# Start the service
docker-compose -f docker-compose.yml up -d audiobookshelf

# Check service status
docker-compose -f docker-compose.yml ps

# View logs
docker-compose -f docker-compose.yml logs -f audiobookshelf
```

## 🔧 Configuration

### Docker Compose Configuration
```yaml
audiobookshelf:
  image: ghcr.io/advplyr/audiobookshelf:latest
  container_name: audiobookshelf
  environment:
    - PUID=1029
    - PGID=100
    - TZ=America/Los_Angeles
  volumes:
    - /volume2/metadata/docker2/audiobookshelf:/config
    - /volume1/data/media/audiobooks:/audiobooks
    - /volume1/data/media/podcasts:/podcasts
    - /volume1/data/media/ebooks:/ebooks
  ports:
    - "13378:80"
  networks:
    media2_net:
      ipv4_address: 172.24.0.16
  security_opt:
    - no-new-privileges:true
  restart: always
```

### Environment Variables
| Variable | Value | Description |
|----------|-------|-------------|
| `PUID` | `1029` | User ID for file permissions |
| `PGID` | `100` | Group ID for file permissions |
| `TZ` | `America/Los_Angeles` | Timezone setting |

### Port Mappings
| Host Port | Container Port | Protocol | Purpose |
|-----------|----------------|----------|----------|
| 13378 | 80 | TCP | Web UI |

### Volume Mappings
| Host Path | Container Path | Type | Purpose |
|-----------|----------------|------|----------|
| `/volume2/metadata/docker2/audiobookshelf` | `/config` | bind | Configuration & database |
| `/volume1/data/media/audiobooks` | `/audiobooks` | bind | Audiobook library |
| `/volume1/data/media/podcasts` | `/podcasts` | bind | Podcast library |
| `/volume1/data/media/ebooks` | `/ebooks` | bind | Ebook library |

## 🌐 Access Information

| Interface | URL |
|-----------|-----|
| Web UI | `http://192.168.0.200:13378` |

### Mobile Apps
- **iOS**: Search "Audiobookshelf" on App Store
- **Android**: Search "Audiobookshelf" on Play Store
- **Server Address**: `http://192.168.0.200:13378`

## 🔧 Initial Setup

### 1. Create Admin Account
On first launch, you'll be prompted to create an admin account.

### 2. Create Libraries
Go to **Settings → Libraries** and create:

| Library Name | Type | Folder Path |
|--------------|------|-------------|
| Audiobooks | Audiobook | `/audiobooks` |
| Ebooks | Book | `/ebooks` |
| Podcasts | Podcast | `/podcasts` |

### 3. Enable Folder Watching
In each library's settings, enable **Watch for changes** to auto-import new files when LazyLibrarian downloads them.

## 🔒 Security Considerations

- ✅ Security options configured (no-new-privileges)
- ✅ Running with specific user/group IDs
- ⚠️ Consider setting up authentication for remote access
- ⚠️ Use HTTPS via reverse proxy for external access

## 📊 Resource Requirements

### Recommended Resources
- **Minimum RAM**: 256MB
- **Recommended RAM**: 512MB+
- **CPU**: 1 core minimum
- **Storage**: Varies by library size (metadata + cover art cache)

### Resource Monitoring
```bash
docker stats audiobookshelf
```

## ✨ Key Features

- **Progress Sync**: Automatically syncs listening/reading progress across devices
- **Chapter Support**: Navigate audiobooks by chapter
- **Multiple Users**: Each user has their own library progress
- **Podcast Support**: Subscribe and auto-download podcasts
- **Ebook Support**: Read ebooks directly in the app
- **Offline Mode**: Download audiobooks to mobile devices
- **Metadata Matching**: Auto-fetches book metadata and cover art

## 🚨 Troubleshooting

### Common Issues

**Books not appearing**
- Check file permissions match PUID/PGID
- Verify folder paths are correct
- Manually scan library: Library → Scan

**Progress not syncing**
- Ensure you're logged into the same account
- Check network connectivity
- Force sync in mobile app settings

**Mobile app can't connect**
- Verify server address is correct
- Check firewall allows port 13378
- Ensure device is on same network (or use VPN)

**Metadata not found**
- Try manual match: Book → Match
- Check audiobook folder naming (Author - Title format works best)
- Ensure file metadata tags are correct

### Useful Commands
```bash
# View real-time logs
docker logs -f audiobookshelf

# Restart service
docker restart audiobookshelf

# Update service
docker pull ghcr.io/advplyr/audiobookshelf:latest
docker restart audiobookshelf

# Backup database
cp -r /volume2/metadata/docker2/audiobookshelf /backup/audiobookshelf-$(date +%Y%m%d)
```

## 📂 Recommended Folder Structure

For best metadata matching:
```
/audiobooks/
├── Author Name/
│   ├── Book Title/
│   │   ├── cover.jpg (optional)
│   │   ├── desc.txt (optional)
│   │   └── *.mp3 or *.m4b
│   └── Another Book/
│       └── ...

/ebooks/
├── Author Name/
│   ├── Book Title.epub
│   └── Another Book.pdf
```

## API Access

| Field | Value |
|-------|-------|
| **URL** | http://192.168.0.200:13378 |
| **API Token (arrssuite key)** | `REDACTED_ABS_API_TOKEN` |

```bash
ABS="http://192.168.0.200:13378"
ABS_KEY="REDACTED_ABS_API_TOKEN"

# List libraries
curl -s "$ABS/api/libraries" -H "Authorization: Bearer $ABS_KEY" | python3 -m json.tool

# List items in a library
curl -s "$ABS/api/libraries/<library-id>/items" -H "Authorization: Bearer $ABS_KEY" | python3 -m json.tool

# Trigger scan on a library
curl -s -X POST "$ABS/api/libraries/<library-id>/scan" -H "Authorization: Bearer $ABS_KEY"
```

### Library IDs

| Library | ID |
|---------|----|
| Audiobook | `d36776eb-fe81-467f-8fee-19435ee2827b` |
| Ebooks | `5af23ed3-f69d-479b-88bc-1c4911c99d2d` |
| Podcast | `6fc11431-ec84-4c96-8bec-b2638fff57e7` |

## 📚 Additional Resources

- **Official Documentation**: [Audiobookshelf Docs](https://www.audiobookshelf.org/docs)
- **GitHub**: [advplyr/audiobookshelf](https://github.com/advplyr/audiobookshelf)
- **Discord**: Active community support

## 🔗 Related Services

Services REDACTED_APP_PASSWORD Audiobookshelf:
- LazyLibrarian (automated downloads)
- Calibre (ebook management)
- Prowlarr (indexer management)

---

*Last Updated*: 2025-01-20  
*Configuration Source*: `hosts/synology/atlantis/arr-suite/docker-compose.yml`