containerize & enhance filtering

2026-02-08 11:58:22 -05:00
parent 25ef2adf71
commit 312c54c5bd
8 changed files with 608 additions and 19 deletions
--- a/README.md
+++ b/README.md
@@ -7,9 +7,42 @@ Automatically copy or clear Live TV channel logos in Emby Server.
 - **Copy Mode** (default): Copies the Primary logo (Logo Dark Version) to LogoLight (Logo Light Version) and LogoLightColor (Logo Light with Colour) for all TV channels
 - **Clear Mode** (`--clear`): Removes all logos (Primary, LogoLight, LogoLightColor) from channels

+## Quick Start (Docker - Recommended)
+
+1. **Copy the environment template:**
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Edit `.env` and set your Emby credentials:**
+   ```bash
+   EMBY_SERVER_URL=https://your-emby-server.com
+   EMBY_API_KEY=your_api_key_here
+   ```
+
+3. **Test with dry run on first channel:**
+   ```bash
+   docker compose up
+   ```
+
+4. **When ready, enable execution:**
+   Edit `.env` and set:
+   ```bash
+   DRY_RUN=false
+   FIRST_ONLY=false
+   ```
+
+5. **Run in the background:**
+   ```bash
+   docker compose up -d
+   ```
+
+See the [Docker Usage](#docker-usage-recommended) section for detailed configuration.
+
 ## Requirements

- Python 3.6+
+- **Docker** (recommended): Docker and Docker Compose - uses pre-built image from GHCR
+- **Python** (alternative): Python 3.6+
 - Emby Server with API access
 - API key from Emby Server

@@ -19,7 +52,161 @@ Automatically copy or clear Live TV channel logos in Emby Server.
 2. Go to Settings → Advanced → API Keys
 3. Create a new API key or use an existing one

-## Usage
+## Docker Usage (Recommended)
+
+### Configuration
+
+All configuration is done via the `.env` file. Copy `.env.example` to `.env` and customize:
+
+```bash
+cp .env.example .env
+```
+
+#### Required Settings
+
+| Variable | Description |
+|----------|-------------|
+| `EMBY_SERVER_URL` | Your Emby server URL (e.g., `https://emby.example.com`) |
+| `EMBY_API_KEY` | Your Emby API key |
+
+#### Optional Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MODE` | `copy` | Operation mode: `copy` (copy logos) or `clear` (delete logos) |
+| `DRY_RUN` | `true` | `true` = simulate only, `false` = execute changes |
+| `FIRST_ONLY` | `false` | `true` = process first channel only (for testing) |
+| `FORCE` | `false` | `true` = overwrite existing logos (copy mode only) |
+| `TAGS` | _(empty)_ | Comma-separated list of tags to filter channels (e.g., `sports,news`) |
+| `LIST_TAGS` | `false` | `true` = list all available tags and exit |
+| `CRON_SCHEDULE` | `0 3 * * *` | Cron schedule (default: daily at 3 AM) |
+| `RUN_ONCE` | `false` | `true` = run once and exit, `false` = run on schedule |
+| `TZ` | `UTC` | Timezone for cron (e.g., `America/New_York`) |
+
+### Common Scenarios
+
+#### Discover Available Tags
+```bash
+# In .env:
+LIST_TAGS=true
+RUN_ONCE=true
+
+# Run:
+docker compose up
+```
+
+#### Safe Testing (Recommended First Run)
+```bash
+# In .env:
+MODE=copy
+DRY_RUN=true
+FIRST_ONLY=true
+
+# Run:
+docker compose up
+```
+
+#### Production - Daily Updates
+```bash
+# In .env:
+MODE=copy
+DRY_RUN=false
+CRON_SCHEDULE=0 3 * * *
+
+# Run in background:
+docker compose up -d
+```
+
+#### One-Time Update Now
+```bash
+# In .env:
+MODE=copy
+DRY_RUN=false
+RUN_ONCE=true
+
+# Run:
+docker compose up
+```
+
+#### Force Overwrite Existing Logos
+```bash
+# In .env:
+MODE=copy
+DRY_RUN=false
+FORCE=true
+
+# Run:
+docker compose up -d
+```
+
+#### Clear All Logos (Use with Caution!)
+```bash
+# In .env:
+MODE=clear
+DRY_RUN=false
+
+# Run:
+docker compose up
+```
+
+#### Process Only Channels with Specific Tags
+```bash
+# In .env:
+MODE=copy
+DRY_RUN=false
+TAGS=sports,news
+
+# Run:
+docker compose up -d
+```
+
+#### Force Update Sports Channels Only
+```bash
+# In .env:
+MODE=copy
+DRY_RUN=false
+FORCE=true
+TAGS=sports
+
+# Run:
+docker compose up
+```
+
+### Docker Commands
+
+```bash
+# Build and start
+docker compose up
+
+# Start in background
+docker compose up -d
+
+# View logs
+docker compose logs -f
+
+# Stop
+docker compose down
+
+# Build locally (if modifying source)
+# Uncomment "build: ." in docker-compose.yml, then:
+docker compose up --build
+```
+
+### Cron Schedule Examples
+
+Format: `minute hour day month weekday`
+
+| Schedule | Description |
+|----------|-------------|
+| `0 3 * * *` | Daily at 3 AM (default) |
+| `0 */6 * * *` | Every 6 hours |
+| `0 0 * * 0` | Weekly on Sunday at midnight |
+| `0 2 1 * *` | Monthly on the 1st at 2 AM |
+| `*/30 * * * *` | Every 30 minutes |
+
+## Python Usage (Alternative)
+
+If you prefer to run the script directly with Python instead of Docker:

 ### Copy Logos (Default Mode)

@@ -76,35 +263,49 @@ python update_channel_logos.py \
 | `--first-only` | Only process the first channel (useful for testing) |
 | `--clear` | Clear all logos instead of copying them |
 | `--force` | Overwrite existing LogoLight/LogoLightColor (copy mode only) |
+| `--tags` | Comma-separated list of tags to filter channels (e.g., `sports,news`) |
+| `--list-tags` | List all available tags and exit |
+| `--non-interactive` | Skip confirmation prompts (for automated execution) |

 ## Examples

 **Recommended workflow:**

-1. Test on first channel with dry run:
+1. Discover available tags:
+   ```bash
+   python update_channel_logos.py --server URL --api-key KEY --list-tags
+   ```
+
+2. Test on first channel with dry run:
   ```bash
   python update_channel_logos.py --server URL --api-key KEY --first-only
   ```

-2. Execute on first channel:
+3. Execute on first channel:
   ```bash
   python update_channel_logos.py --server URL --api-key KEY --first-only --execute
   ```

-3. If successful, run on all channels:
+4. If successful, run on all channels:
   ```bash
   python update_channel_logos.py --server URL --api-key KEY --execute
   ```

+5. Process only channels with specific tags:
+   ```bash
+   python update_channel_logos.py --server URL --api-key KEY --tags sports,news --execute
+   ```
+
 ## How It Works

 1. Connects to your Emby server
 2. Fetches all Live TV channels
-3. For each channel:
+3. Filters channels by tags (if specified)
+4. For each channel:
   - **Copy mode**: Downloads the Primary logo and uploads it as LogoLight and LogoLightColor
   - **Clear mode**: Deletes Primary, LogoLight, and LogoLightColor
-4. Skips channels that already have the logos (copy mode, unless `--force` is used) or have no logos (clear mode)
-5. Shows a summary of results
+5. Skips channels that already have the logos (copy mode, unless `--force` is used) or have no logos (clear mode)
+6. Shows a summary of results

 ## Safety Features