jesmann/zap2xml repository overview

⁠zap2xml

Automate TV guides to XMLTV format. Easy to use, up-to-date. See below for getting started.

⁠Recent updates

⁠(2025-08-20)

• Changed default Sort option to the Channel Number in Lineup if available
• Added '--stationid' to sort the previous way by StationID
• Added --sortname to sort by the Call Sign

⁠(2025-08-18)

• Changed URL pull to match output from page when stopped working
• Added Display Name with Channel Number and Call Sign to mirror previous Perl Script
• Added --nextpvr option to list Channel Number Call Sign first

⁠(2025-08-09)

• Restored <episode-num system="dd_progid"> tag that Plex uses that was missing.
• Fixed Sorting so output is listed by Channel ID (common station/gracenote id) then by date/time.

⁠(2025-08-07)

• Reordered Program fields to match original Perl script output
• --postalCode not required as long as Country and lineup Id correct except Over the Air
• Moved <date> above <category> to match original Perl output. Corrected where Movie Release Year is properly displayed.
• Added <length> tag.
• Updated channel logo no longer has fixed width so can display in better quality

⁠(2025-08-06)

• Added Valid Country Codes that can be used
• Added --mediaportal option to use <episode-num system="xmltv_ns"> before others so Media Portal will display Season/Episode properly

⁠(2025-08-05)

Changes since previous release

• Added Category if available (Movie, Sports, News, Talk, Family etc)
• Added Category "Series" to all programs that did not return a category
• Added additional Season Episode formats for various players
• Added year as Season for programs that only list an episode number like daily cable news
• Added tag to all programs without an aired date normalized to America/New York
• Added xmltv_ns with the date aired as Season YYYY Episode MMYY to Non Movie or Sports with no other Season/Episode like local news so would have the ability to record as Series is most players.
• Added URL to program details from old Perl function.
• Added --appendAsterisk to add * to title on programs that are New and/or Live
• Added tag to programs that are not and/or
• Updated affiliateId after orbebb stopped working
• Updated Docker with these changes use APPEND_ASTERISK: TRUE for the --appendAsterisk option

⁠How to use

⁠Docker

⁠docker-compose

services:
  zap2xml:
    container_name: zap2xml
    image: jesmannstl/zap2xml:latest
    environment:
      OUTPUT_FILE: /xmltv/xmltv.xml
    volumes:
      - ./xmltv:/xmltv
    restart: unless-stopped

⁠docker run

For a simple Docker run command:

docker run -d --name zap2xml \
  -v /path/to/output:/xmltv \
  -e OUTPUT_FILE=/xmltv/xmltv.xml \
  jesmannstl/zap2xml:latest

⁠Configuration

⁠Environment variables

⁠Running in Docker

The SLEEP_TIME environment variable can be used to set the interval between runs. The default is 21600 seconds (6 hours).

⁠FAQ

⁠How do I get my Lineup ID?

Visit tvtv.us or tvtv.ca find your lineup and the lineupid is in the url. Example Directv New York in Zip Code 10001 is https://www.tvtv.us/ny/new-york/10001/luUSA-DITV501-X⁠ the lineupId is USA-DITV501-X See wiki at https://github.com/jesmannstl/zap2xml/wiki⁠ for a lot more

⁠Running native in node.js

You can also run natively on your computer for that option visit http://github.com/jesmannstl/zap2xml⁠