From bc74ac6f06664ce8df8db14e5d6a01c46c51b4be Mon Sep 17 00:00:00 2001 From: Jef LeCompte Date: Tue, 15 Jul 2025 16:26:08 -0700 Subject: [PATCH] docs: better descriptions closes #8 --- .gitignore | 4 +++ .zap2xmlrc-example | 63 ++++++++++++++++++++++++++++-------- README.md | 81 ++++++++++++++++++++++++++++++++++++++++------ entrypoint.sh | 3 +- 4 files changed, 126 insertions(+), 25 deletions(-) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fade825 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +.zap2xmlrc + +config/ +xmltv/ diff --git a/.zap2xmlrc-example b/.zap2xmlrc-example index 828ffec..6263e8e 100644 --- a/.zap2xmlrc-example +++ b/.zap2xmlrc-example @@ -1,20 +1,57 @@ +# Basic settings +# start: Number of days to offset from today for the start date (default: 0, cmd: -s) start=0 +# days: Number of days of program data to fetch (default: 7, cmd: -d) days=7 -ncdays=0 -ncsdays=0 -ncmday=-1 +# retries: Number of connection retries before failure (default: 3, max: 20, cmd: -r) retries=3 -user=user -pass=password + +# Authentication +# user: Username/email for Zap2it account (default: empty, cmd: -u) +user=myemail@example.com +# pass: Password for Zap2it account (default: empty, cmd: -p) +pass=mypassword + +# Cache settings +# cache: Directory to store cached data files (default: cache, cmd: -c) cache=/config/cache -icon=/config/icons -trailer=/config/trailers -lang=en -proxy=http://localhost:8080 +# ncdays: Number of days from the end to not cache (default: 0, cmd: -n) +ncdays=0 +# ncsdays: Number of days from the start to not cache (default: 0, cmd: -N) +ncsdays=0 +# ncmday: Specific day number to not cache, 1-based relative to start (default: -1, cmd: -B) +ncmday=-1 + +# Output settings +# outfile: Output XML file path (default: xmltv.xml or xtvd.xml, cmd: -o) outfile=/xmltv/xmltv.xml -outformat=xmltv (or 'xtvd') -lineuptype=type (xtvd only - Cable/CableDigital/Satellite/LocalBroadcast) -lineupname=name (xtvd only) -lineuplocation=location (xtvd only) +# outformat: Output format - xmltv or xtvd (default: xmltv, cmd: -x forces xtvd) +outformat=xmltv + +# Language +# lang: Language code for program data (default: en, cmd: -l) +lang=en + +# Media directories +# icon: Directory to store channel icons (default: disabled, cmd: -i) +icon=/config/icons +# trailer: Directory to store movie trailers (default: disabled, cmd: -t) +trailer=/config/trailers + +# Network +# proxy: HTTP proxy server URL (default: none, cmd: -P) +proxy=http://localhost:8080 + +# XTVD format settings (only used when outformat=xtvd) +# lineuptype: Type of lineup - Cable/CableDigital/Satellite/LocalBroadcast (default: none) +lineuptype=Cable +# lineupname: Name of the lineup (default: none) +lineupname=My Cable Provider +# lineuplocation: Location of the lineup (default: none) +lineuplocation=New York, NY + +# Alternative authentication (TV Guide) +# lineupid: Lineup ID for TV Guide, alternative to username/password (default: none, cmd: -Y) lineupid=X:80000 +# postalcode: Postal code for TV Guide lineup lookup (default: none, cmd: -Z) postalcode=01010 diff --git a/README.md b/README.md index 7755966..57ab0fc 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,12 @@ See [zap2xml](https://web.archive.org/web/20200426004001/zap2xml.awardspace.info ## Docker -| Tag | Description | -|---|---| -| latest | Stable zap2xml releases | -| nightly | HEAD zap2xml release | +| Tag | Description | +| ------- | ----------------------- | +| latest | Stable zap2xml releases | +| nightly | HEAD zap2xml release | -### Compose +### docker-compose (recommended) ```yaml services: @@ -19,11 +19,72 @@ services: environment: OPT_ARGS: >- -I -D -C /config/.zap2xmlrc -o /xmltv/xmltv.xml - SLEEPTIME: 43200 # 12 hours in seconds - TZ: America/New_York - USER_AGENT: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" # Optional: customize user agent + TZ: America/New_York # Consider using your timezone volumes: - - /path/to/appdata/zap2xml:/config - - /path/to/appdata/xmltv:/xmltv # nice for mapping other drives to this that may use xmltv.xml + - /path/to/zap2xml/config:/config + - /path/to/xmltv:/xmltv # nice for mapping other drives to this that may use xmltv.xml restart: unless-stopped ``` + +## Configuration + +### Optional environment variables + +| Variable | Description | Type | Default | +| ------------ | ---------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | +| `USER_AGENT` | Custom user agent string for HTTP requests. | String | `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36` | +| `SLEEPTIME` | Number of seconds to sleep between runs (useful for scheduling in Docker or cron). | Integer | `43200` | +| `TZ` | Timezone for program times (affects output XML and Perl's time calculations). | String | System default | + +### Optional run configurations + +| Option | Type | Default | Description | Config File | Command Line | +| ---------------- | --------- | ----------- | ------------------------------------------------------ | ----------------------------- | ------------ | +| `start` | Integer | `0` | Number of days to offset from today for the start date | `start=1` | `-s` | +| `days` | Integer | `7` | Number of days of program data to fetch | `days=14` | `-d` | +| `retries` | Integer | `3` | Number of connection retries before failure (max 20) | `retries=5` | `-r` | +| `user` | String | (empty) | Username/email for Zap2it account | `user=myemail@example.com` | `-u` | +| `pass` | String | (empty) | Password for Zap2it account | `pass=mypassword` | `-p` | +| `cache` | Directory | `cache` | Directory to store cached data files | `cache=/config/cache` | `-c` | +| `ncdays` | Integer | `0` | Number of days from the end to not cache | `ncdays=2` | `-n` | +| `ncsdays` | Integer | `0` | Number of days from the start to not cache | `ncsdays=1` | `-N` | +| `ncmday` | Integer | `-1` | Specific day number to not cache (1-based) | `ncmday=3` | `-B` | +| `outfile` | File path | `xmltv.xml` | Output XML file path | `outfile=/xmltv/xmltv.xml` | `-o` | +| `outformat` | String | `xmltv` | Output format (xmltv/xtvd) | `outformat=xtvd` | `-x` | +| `lang` | String | `en` | Language code for program data | `lang=es` | `-l` | +| `icon` | Directory | (disabled) | Directory to store channel icons | `icon=/config/icons` | `-i` | +| `trailer` | Directory | (disabled) | Directory to store movie trailers | `trailer=/config/trailers` | `-t` | +| `proxy` | URL | (none) | HTTP proxy server URL | `proxy=http://localhost:8080` | `-P` | +| `lineuptype` | String | (none) | Type of lineup (XTVD only) | `lineuptype=Cable` | - | +| `lineupname` | String | (none) | Name of the lineup (XTVD only) | `lineupname=My Provider` | - | +| `lineuplocation` | String | (none) | Location of the lineup (XTVD only) | `lineuplocation=New York, NY` | - | +| `lineupid` | String | (none) | Lineup ID for TV Guide | `lineupid=X:80000` | `-Y` | +| `postalcode` | String | (none) | Postal code for TV Guide | `postalcode=01010` | `-Z` | +| `shiftMinutes` | Integer | `0` | Offset program times by minutes | - | `-m` | +| `sleeptime` | Integer | `0` | Sleep between requests (seconds) | - | `-S` | +| `allChan` | Boolean | `false` | Output all channels (not just favorites) | - | `-a` | +| `outputXTVD` | Boolean | `false` | Force XTVD output format | - | `-x` | +| `includeDetails` | Boolean | `false` | Include program details (extra requests) | - | `-D` | +| `includeIcons` | Boolean | `false` | Include program icons (extra requests) | - | `-I` | +| `retainOrder` | Boolean | `false` | Retain website channel order | - | `-b` | +| `quiet` | Boolean | `false` | Quiet mode (no status output) | - | `-q` | +| `wait` | Boolean | `false` | Wait on exit (require keypress) | - | `-w` | +| `hexEncode` | Boolean | `false` | Hex encode HTML entities | - | `-e` | +| `utf8` | Boolean | `false` | UTF-8 encoding (default: ISO-8859-1) | - | `-U` | +| `liveTag` | Boolean | `false` | Output `` tag | - | `-L` | +| `noTBA` | Boolean | `false` | Don't cache files with "TBA" titles | - | `-T` | +| `channelFirst` | Boolean | `false` | Output channel names first | - | `-F` | +| `oldStyle` | Boolean | `false` | Use old tv_grab_na style channel IDs | - | `-O` | +| `appendFlags` | String | (none) | Append flags to program titles | - | `-A` | +| `copyYear` | Boolean | `false` | Copy movie_year to sub-title tags | - | `-M` | +| `addSeries` | Boolean | `false` | Add "series" category to non-movies | - | `-j` | +| `includeXMLTV` | File | (none) | Include XMLTV file in output | - | `-J` | +| `useTVGuide` | Boolean | `false` | Use tvguide.com instead of gracenote.com | - | `-z` | + +### Notes + +- Configuration file values can be overridden by command line options +- The configuration file supports comments (lines starting with `#`) +- Empty lines are ignored +- Values are trimmed of leading/trailing whitespace +- Boolean options (like `outformat=xtvd`) are case-insensitive diff --git a/entrypoint.sh b/entrypoint.sh index 14d4887..f9edb40 100755 --- a/entrypoint.sh +++ b/entrypoint.sh @@ -1,7 +1,6 @@ #!/bin/sh -while : -do +while true; do DATE=$(date) eval /opt/zap2xml.pl "$OPT_ARGS" echo "Last run time: $DATE"