Skip to content

Commit bc74ac6

Browse files
jefjef
committed
docs: better descriptions
closes #8
1 parent 9aae5cd commit bc74ac6

File tree

4 files changed

+123
-22
lines changed

4 files changed

+123
-22
lines changed

‎.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.zap2xmlrc
2+
3+
config/
4+
xmltv/

‎.zap2xmlrc-example

Lines changed: 47 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,57 @@
1+
# Basic settings
2+
# start: Number of days to offset from today for the start date (default: 0, cmd: -s)
13
start=0
4+
# days: Number of days of program data to fetch (default: 7, cmd: -d)
25
days=7
6+
# retries: Number of connection retries before failure (default: 3, max: 20, cmd: -r)
7+
retries=3
8+
9+
# Authentication
10+
# user: Username/email for Zap2it account (default: empty, cmd: -u)
11+
user=myemail@example.com
12+
# pass: Password for Zap2it account (default: empty, cmd: -p)
13+
pass=mypassword
14+
15+
# Cache settings
16+
# cache: Directory to store cached data files (default: cache, cmd: -c)
17+
cache=/config/cache
18+
# ncdays: Number of days from the end to not cache (default: 0, cmd: -n)
319
ncdays=0
20+
# ncsdays: Number of days from the start to not cache (default: 0, cmd: -N)
421
ncsdays=0
22+
# ncmday: Specific day number to not cache, 1-based relative to start (default: -1, cmd: -B)
523
ncmday=-1
6-
retries=3
7-
user=user
8-
pass=password
9-
cache=/config/cache
24+
25+
# Output settings
26+
# outfile: Output XML file path (default: xmltv.xml or xtvd.xml, cmd: -o)
27+
outfile=/xmltv/xmltv.xml
28+
# outformat: Output format - xmltv or xtvd (default: xmltv, cmd: -x forces xtvd)
29+
outformat=xmltv
30+
31+
# Language
32+
# lang: Language code for program data (default: en, cmd: -l)
33+
lang=en
34+
35+
# Media directories
36+
# icon: Directory to store channel icons (default: disabled, cmd: -i)
1037
icon=/config/icons
38+
# trailer: Directory to store movie trailers (default: disabled, cmd: -t)
1139
trailer=/config/trailers
12-
lang=en
40+
41+
# Network
42+
# proxy: HTTP proxy server URL (default: none, cmd: -P)
1343
proxy=http://localhost:8080
14-
outfile=/xmltv/xmltv.xml
15-
outformat=xmltv (or 'xtvd')
16-
lineuptype=type (xtvd only - Cable/CableDigital/Satellite/LocalBroadcast)
17-
lineupname=name (xtvd only)
18-
lineuplocation=location (xtvd only)
44+
45+
# XTVD format settings (only used when outformat=xtvd)
46+
# lineuptype: Type of lineup - Cable/CableDigital/Satellite/LocalBroadcast (default: none)
47+
lineuptype=Cable
48+
# lineupname: Name of the lineup (default: none)
49+
lineupname=My Cable Provider
50+
# lineuplocation: Location of the lineup (default: none)
51+
lineuplocation=New York, NY
52+
53+
# Alternative authentication (TV Guide)
54+
# lineupid: Lineup ID for TV Guide, alternative to username/password (default: none, cmd: -Y)
1955
lineupid=X:80000
56+
# postalcode: Postal code for TV Guide lineup lookup (default: none, cmd: -Z)
2057
postalcode=01010

‎README.md

Lines changed: 71 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,12 @@ See [zap2xml](https://web.archive.org/web/20200426004001/zap2xml.awardspace.info
44

55
## Docker
66

7-
| Tag | Description |
8-
|---|---|
9-
| latest | Stable zap2xml releases |
10-
| nightly | HEAD zap2xml release |
7+
| Tag | Description |
8+
| ------- | ----------------------- |
9+
| latest | Stable zap2xml releases |
10+
| nightly | HEAD zap2xml release |
1111

12-
### Compose
12+
### docker-compose (recommended)
1313

1414
```yaml
1515
services:
@@ -19,11 +19,72 @@ services:
1919
environment:
2020
OPT_ARGS: >-
2121
-I -D -C /config/.zap2xmlrc -o /xmltv/xmltv.xml
22-
SLEEPTIME: 43200 # 12 hours in seconds
23-
TZ: America/New_York
24-
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
22+
TZ: America/New_York # Consider using your timezone
2523
volumes:
26-
- /path/to/appdata/zap2xml:/config
27-
- /path/to/appdata/xmltv:/xmltv # nice for mapping other drives to this that may use xmltv.xml
24+
- /path/to/zap2xml/config:/config
25+
- /path/to/xmltv:/xmltv # nice for mapping other drives to this that may use xmltv.xml
2826
restart: unless-stopped
2927
```
28+
29+
## Configuration
30+
31+
### Optional environment variables
32+
33+
| Variable | Description | Type | Default |
34+
| ------------ | ---------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
35+
| `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` |
36+
| `SLEEPTIME` | Number of seconds to sleep between runs (useful for scheduling in Docker or cron). | Integer | `43200` |
37+
| `TZ` | Timezone for program times (affects output XML and Perl's time calculations). | String | System default |
38+
39+
### Optional run configurations
40+
41+
| Option | Type | Default | Description | Config File | Command Line |
42+
| ---------------- | --------- | ----------- | ------------------------------------------------------ | ----------------------------- | ------------ |
43+
| `start` | Integer | `0` | Number of days to offset from today for the start date | `start=1` | `-s` |
44+
| `days` | Integer | `7` | Number of days of program data to fetch | `days=14` | `-d` |
45+
| `retries` | Integer | `3` | Number of connection retries before failure (max 20) | `retries=5` | `-r` |
46+
| `user` | String | (empty) | Username/email for Zap2it account | `user=myemail@example.com` | `-u` |
47+
| `pass` | String | (empty) | Password for Zap2it account | `pass=mypassword` | `-p` |
48+
| `cache` | Directory | `cache` | Directory to store cached data files | `cache=/config/cache` | `-c` |
49+
| `ncdays` | Integer | `0` | Number of days from the end to not cache | `ncdays=2` | `-n` |
50+
| `ncsdays` | Integer | `0` | Number of days from the start to not cache | `ncsdays=1` | `-N` |
51+
| `ncmday` | Integer | `-1` | Specific day number to not cache (1-based) | `ncmday=3` | `-B` |
52+
| `outfile` | File path | `xmltv.xml` | Output XML file path | `outfile=/xmltv/xmltv.xml` | `-o` |
53+
| `outformat` | String | `xmltv` | Output format (xmltv/xtvd) | `outformat=xtvd` | `-x` |
54+
| `lang` | String | `en` | Language code for program data | `lang=es` | `-l` |
55+
| `icon` | Directory | (disabled) | Directory to store channel icons | `icon=/config/icons` | `-i` |
56+
| `trailer` | Directory | (disabled) | Directory to store movie trailers | `trailer=/config/trailers` | `-t` |
57+
| `proxy` | URL | (none) | HTTP proxy server URL | `proxy=http://localhost:8080` | `-P` |
58+
| `lineuptype` | String | (none) | Type of lineup (XTVD only) | `lineuptype=Cable` | - |
59+
| `lineupname` | String | (none) | Name of the lineup (XTVD only) | `lineupname=My Provider` | - |
60+
| `lineuplocation` | String | (none) | Location of the lineup (XTVD only) | `lineuplocation=New York, NY` | - |
61+
| `lineupid` | String | (none) | Lineup ID for TV Guide | `lineupid=X:80000` | `-Y` |
62+
| `postalcode` | String | (none) | Postal code for TV Guide | `postalcode=01010` | `-Z` |
63+
| `shiftMinutes` | Integer | `0` | Offset program times by minutes | - | `-m` |
64+
| `sleeptime` | Integer | `0` | Sleep between requests (seconds) | - | `-S` |
65+
| `allChan` | Boolean | `false` | Output all channels (not just favorites) | - | `-a` |
66+
| `outputXTVD` | Boolean | `false` | Force XTVD output format | - | `-x` |
67+
| `includeDetails` | Boolean | `false` | Include program details (extra requests) | - | `-D` |
68+
| `includeIcons` | Boolean | `false` | Include program icons (extra requests) | - | `-I` |
69+
| `retainOrder` | Boolean | `false` | Retain website channel order | - | `-b` |
70+
| `quiet` | Boolean | `false` | Quiet mode (no status output) | - | `-q` |
71+
| `wait` | Boolean | `false` | Wait on exit (require keypress) | - | `-w` |
72+
| `hexEncode` | Boolean | `false` | Hex encode HTML entities | - | `-e` |
73+
| `utf8` | Boolean | `false` | UTF-8 encoding (default: ISO-8859-1) | - | `-U` |
74+
| `liveTag` | Boolean | `false` | Output `<live />` tag | - | `-L` |
75+
| `noTBA` | Boolean | `false` | Don't cache files with "TBA" titles | - | `-T` |
76+
| `channelFirst` | Boolean | `false` | Output channel names first | - | `-F` |
77+
| `oldStyle` | Boolean | `false` | Use old tv_grab_na style channel IDs | - | `-O` |
78+
| `appendFlags` | String | (none) | Append flags to program titles | - | `-A` |
79+
| `copyYear` | Boolean | `false` | Copy movie_year to sub-title tags | - | `-M` |
80+
| `addSeries` | Boolean | `false` | Add "series" category to non-movies | - | `-j` |
81+
| `includeXMLTV` | File | (none) | Include XMLTV file in output | - | `-J` |
82+
| `useTVGuide` | Boolean | `false` | Use tvguide.com instead of gracenote.com | - | `-z` |
83+
84+
### Notes
85+
86+
- Configuration file values can be overridden by command line options
87+
- The configuration file supports comments (lines starting with `#`)
88+
- Empty lines are ignored
89+
- Values are trimmed of leading/trailing whitespace
90+
- Boolean options (like `outformat=xtvd`) are case-insensitive

‎entrypoint.sh

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
#!/bin/sh
22

3-
while :
4-
do
3+
while true; do
54
DATE=$(date)
65
eval /opt/zap2xml.pl "$OPT_ARGS"
76
echo "Last run time: $DATE"

0 commit comments

Comments
 (0)