homelab-optimized/docs/services/individual/bazarr-enhanced.md

# Bazarr - Enhanced Subtitle Management

**🟢 Media Service - Subtitle Management**

## 📋 Service Overview

| Property | Value |
|----------|-------|
| **Service Name** | bazarr |
| **Host** | Atlantis |
| **Category** | Media |
| **Difficulty** | 🟢 |
| **Docker Image** | `linuxserver/bazarr:latest` |
| **Compose File** | `Atlantis/arr-suite/docker-compose.yml` |
| **Directory** | `Atlantis` |
| **Port** | 6767 |
| **API Key** | `057875988c90c9b05722df7ff5fedc69` |

## 🎯 Purpose

Bazarr is a companion application to Sonarr and Radarr that manages and downloads subtitles for your media library. It automatically searches for and downloads subtitles in your preferred languages, with support for multiple subtitle providers and advanced language profiles.

## ✨ Recent Enhancements (February 2025)

### 🚀 **Subtitle Provider Expansion (4 → 7 providers)**

**Previous Setup (4 providers):**
- ✅ REDACTED_APP_PASSWORD (VIP account)
- ✅ yifysubtitles 
- ✅ animetosho
- ✅ podnapisi

**NEW Providers Added (3 additional):**
- ✅ **addic7ed** - Premium TV show subtitles with fast releases
- ✅ **subf2m** - Comprehensive movie subtitle coverage  
- ✅ **legendasdivx** - International content specialization

### 🎬 **Optimized for Specific Use Cases:**

**Anime Content**: 
- animetosho provider handles dual-audio anime perfectly
- English subtitles prioritized when available
- Japanese fallback support for anime-only content

**International Films** (e.g., "Cold War"):
- Enhanced coverage for non-English original language films
- legendasdivx and subf2m provide better international subtitle sources
- VIP OpenSubtitles account ensures premium access

**TV Shows**:
- addic7ed provides high-quality, fast TV show subtitles
- Community-driven quality control
- Rapid release timing for popular series

### 🔧 **Configuration Improvements:**

1. **Enhanced Provider Coverage**: 75% increase in subtitle sources
2. **Language Profile**: English-focused with proper fallback handling
3. **Quality Scoring**: Optimized minimum scores (80 for series, 60 for movies)
4. **VIP Account Utilization**: OpenSubtitles VIP credentials properly configured
5. **Anime Support**: animetosho provider optimized for anime content

## 🚀 Quick Start

### Prerequisites
- Docker and Docker Compose installed
- Sonarr and Radarr configured
- Access to the host system (Atlantis)

### Deployment
```bash
# Navigate to service directory
cd /volume1/docker/arr-suite

# Start the service
docker-compose up -d bazarr

# Check service status
docker-compose ps bazarr

# View logs
docker-compose logs -f bazarr
```

## 🔧 Configuration

### Docker Compose Configuration
```yaml
bazarr:
  container_name: bazarr
  environment:
    - PUID=1027
    - PGID=65536
    - TZ=America/Los_Angeles
    - UMASK=022
  image: linuxserver/bazarr:latest
  networks:
    media_net:
      ipv4_address: 172.23.0.9
  ports:
    - 6767:6767/tcp
  restart: always
  security_opt:
    - no-new-privileges:true
  volumes:
    - /volume1/docker2/bazarr:/config
    - /volume1/data:/data
```

### Environment Variables
| Variable | Value | Description |
|----------|-------|-------------|
| `PUID` | `1027` | User ID for file permissions |
| `PGID` | `65536` | Group ID for file permissions |
| `TZ` | `America/Los_Angeles` | Timezone setting |
| `UMASK` | `022` | File permission mask |

### Port Mappings
| Host Port | Container Port | Protocol | Purpose |
|-----------|----------------|----------|----------|
| 6767 | 6767 | TCP | Web interface and API |

### Volume Mappings
| Host Path | Container Path | Type | Purpose |
|-----------|----------------|------|----------|
| `/volume1/docker2/bazarr` | `/config` | bind | Configuration files and database |
| `/volume1/data` | `/data` | bind | Media library access |

## 🎛️ Advanced Configuration

### Subtitle Providers Configuration

**Active Providers (7 total):**

1. **OpenSubtitles.com (VIP)**
   - Premium account with enhanced limits
   - Comprehensive language support
   - High-quality community subtitles

2. **addic7ed**
   - Specializes in TV show subtitles
   - Fast release timing
   - Community-moderated quality

3. **yifysubtitles**
   - Movie-focused provider
   - Good coverage for popular films
   - Reliable availability

4. **animetosho**
   - Anime-specialized provider
   - Handles dual-audio content
   - Japanese and English support

5. **podnapisi**
   - Multi-language support
   - European content strength
   - Reliable subtitle timing

6. **subf2m**
   - Movie subtitle coverage
   - Fast release availability
   - International film support

7. **legendasdivx**
   - Portuguese/Spanish specialization
   - International film coverage
   - Non-English content strength

### Language Profile Configuration

**Current Profile: "My language profile"**
- **Primary Language**: English
- **Cutoff Score**: 65535 (maximum quality)
- **Minimum Score**: 
  - Series: 80
  - Movies: 60
- **Fallback Support**: Enabled for original language content

### Quality Scoring System

**Optimized Scoring for Different Content Types:**

**TV Series (Minimum Score: 80)**
- Prioritizes addic7ed and OpenSubtitles
- Fast release timing valued
- Community quality control preferred

**Movies (Minimum Score: 60)**
- Broader provider acceptance
- International content support
- Original language preservation

**Anime Content**
- animetosho provider prioritized
- Dual-audio support
- Japanese fallback when English unavailable

## 📊 Current Status

- **System Health**: ✅ No issues detected
- **Active Providers**: 7 total providers enabled
- **Language Support**: English (primary) with proper fallback
- **API Access**: Fully functional with key `057875988c90c9b05722df7ff5fedc69`
- **VIP Account**: OpenSubtitles.com VIP active

## 🔍 Access Information

- **Web Interface**: `http://atlantis:6767` or `http://100.83.230.112:6767`
- **API Endpoint**: `http://atlantis:6767/api`
- **API Key**: `057875988c90c9b05722df7ff5fedc69`

## 🔒 Security Considerations

- ✅ Security options configured (`no-new-privileges:true`)
- ✅ Running as non-root user (PUID/PGID)
- ✅ API key authentication enabled
- ✅ Network isolation via custom network

## 📈 Resource Requirements

### Current Configuration
- **Memory**: No limits set (recommended: 512MB-1GB)
- **CPU**: No limits set (1 core sufficient)
- **Storage**: Configuration ~100MB, cache varies by usage

### Monitoring
```bash
# Monitor resource usage
docker stats bazarr

# Check disk usage
du -sh /volume1/docker2/bazarr
```

## 🏥 Health Monitoring

### API Health Check
```bash
# Check system health
curl -s -H "X-API-KEY: REDACTED_API_KEY" \
  "http://localhost:6767/api/system/health"

# Check provider status
curl -s -H "X-API-KEY: REDACTED_API_KEY" \
  "http://localhost:6767/api/providers"
```

### Manual Health Checks
```bash
# Check container health
docker inspect --format='{{.State.Status}}' bazarr

# View recent logs
docker logs --tail 50 bazarr

# Check provider connectivity
docker exec bazarr curl -f http://localhost:6767/api/system/status
```

## 🛠️ Troubleshooting

### Common Issues

**Subtitles Not Downloading**
1. Check provider status in web interface
2. Verify API keys for premium providers
3. Check language profile configuration
4. Review minimum score settings

**Provider Connection Issues**
```bash
# Check provider status
curl -H "X-API-KEY: REDACTED_API_KEY" \
  "http://localhost:6767/api/providers"

# Test provider connectivity
docker exec bazarr ping opensubtitles.com
```

**Performance Issues**
- Monitor provider response times
- Check subtitle cache size
- Review concurrent download limits
- Verify network connectivity

**Language Profile Problems**
- Verify language codes are correct
- Check cutoff scores aren't too high
- Review provider language support
- Test with manual subtitle search

### Useful Commands
```bash
# Check service status
docker-compose ps bazarr

# View real-time logs
docker-compose logs -f bazarr

# Restart service
docker-compose restart bazarr

# Update service
docker-compose pull bazarr
docker-compose up -d bazarr

# Access service shell
docker-compose exec bazarr /bin/bash

# Check configuration
docker exec bazarr cat /config/config/config.yaml
```

## 🔗 Integration with Arr Suite

### Sonarr Integration
- **API Key**: Configured for automatic episode subtitle downloads
- **Language Profile**: Synced with Sonarr quality profiles
- **Monitoring**: Real-time episode monitoring enabled

### Radarr Integration  
- **API Key**: Configured for automatic movie subtitle downloads
- **Quality Matching**: Aligned with Radarr quality profiles
- **Search Triggers**: Automatic search on movie import

### Recommended Workflow
1. **Media Import**: Sonarr/Radarr imports new content
2. **Automatic Trigger**: Bazarr detects new media
3. **Provider Search**: All 7 providers searched simultaneously
4. **Quality Scoring**: Best subtitle selected based on profile
5. **Download & Sync**: Subtitle downloaded and synced to media

## 📚 Additional Resources

- **Official Documentation**: [Bazarr Wiki](https://wiki.bazarr.media/)
- **Docker Hub**: [linuxserver/bazarr](https://hub.docker.com/r/linuxserver/bazarr)
- **Community Forums**: [Bazarr Discord](https://discord.gg/MH2e2eb)
- **GitHub Issues**: [Bazarr GitHub](https://github.com/morpheus65535/bazarr)
- **Provider Documentation**: [Subtitle Provider Guide](https://wiki.bazarr.media/Additional-Configuration/Providers/)

## 🔗 Related Services

Services that integrate with Bazarr:
- **Sonarr** - TV show management and monitoring
- **Radarr** - Movie management and monitoring  
- **Plex** - Media server and streaming
- **Jellyfin** - Alternative media server
- **Prowlarr** - Indexer management (indirect integration)

## 📝 Change Log

### February 2025 - Major Provider Enhancement
- ✅ Added 3 new subtitle providers (75% increase)
- ✅ Optimized language profiles for anime and international content
- ✅ Enhanced VIP account utilization
- ✅ Improved quality scoring system
- ✅ Added comprehensive documentation

### Previous Updates
- Initial deployment on Atlantis
- Basic provider configuration
- Sonarr/Radarr integration setup

---

*This documentation reflects the enhanced Bazarr configuration with expanded subtitle provider support and optimized language profiles for diverse content types.*

**Last Updated**: February 9, 2025  
**Configuration Source**: `Atlantis/arr-suite/docker-compose.yml`  
**Enhancement Author**: OpenHands Agent