Contributing Guide

How to?
Project Structure
Scripts

How to?

How to add a channel to the guide?

Open the /sites folder and select the source that you know has the guide for the channel you want.

Then in the selected folder open the file *.channels.xml and add to it:

<channel site="SITE" lang="LANGUAGE_CODE" xmltv_id="CHANNEL_ID" site_id="SITE_ID">CHANNEL_NAME</channel>

Attribute	Description	Example
SITE	Site domain name.	`example.com`
LANGUAGE_CODE	Language of the guide (ISO 639-1 code).	`en`
CHANNEL_ID	Channel ID from iptv-org/database. A complete list of supported channels can also be found at https://iptv-org.github.io/.	`BBCOne.uk`
SITE_ID	Unique ID of the channel used in the source.	`bbc1`
CHANNEL_NAME	Name of the channel used in the source.	`BBC 1`

After that just commit all changes and send a pull request.

How to add a new source to the repository?

To do this, you will need to create a new folder in the /sites directory with at least 4 files:

example.com.config.js

This file describes what kind of request we need to send to get the guide for a particular channel on a certain date and how to parse the response.

module.exports = {
  site: 'example.com',
  url({ channel, date }) {
    return `https://example.com/api/${channel.site_id}/${date.format('YYYY-MM-DD')}`
  },
  parser({ content }) {
    try {
      return JSON.parse(content)
    } catch {
      return []
    }
  },
  channels() {
    return []
  }
}

More detailed instructions for this file can be found here: https://github.com/freearhey/epg-grabber#site-config

example.com.test.js

With this file we can test the previously created config and make sure it works as you expect.

const { parser, url } = require('./example.com.config.js')
const dayjs = require('dayjs')
const utc = require('dayjs/plugin/utc')
const customParseFormat = require('dayjs/plugin/customParseFormat')
dayjs.extend(customParseFormat)
dayjs.extend(utc)

const date = dayjs.utc('2025-01-12', 'YYYY-MM-DD').startOf('d')
const channel = { site_id: 'bbc1', xmltv_id: 'BBCOne.uk' }

it('can generate valid url', () => {
  expect(url({ channel, date })).toBe('https://example.com/api/bbc1/2025-01-12')
})

it('can parse response', () => {
  const content =
    '[{"title":"Program 1","start":"2025-01-12T00:00:00.000Z","stop":"2025-01-12T00:30:00.000Z"},{"title":"Program 2","start":"2025-01-12T00:30:00.000Z","stop":"2025-01-12T01:00:00.000Z"}]'

  const results = parser({ content })

  expect(results.length).toBe(2)
  expect(results[0]).toMatchObject({
    title: 'Program 1',
    start: '2025-01-12T00:00:00.000Z',
    stop: '2025-01-12T00:30:00.000Z'
  })
  expect(results[1]).toMatchObject({
    title: 'Program 2',
    start: '2025-01-12T00:30:00.000Z',
    stop: '2025-01-12T01:00:00.000Z'
  })
})

it('can handle empty guide', () => {
  const result = parser({
    date,
    channel,
    content: ''
  })

  expect(result).toMatchObject([])
})

To run all of these tests use the following command:

npm test --- example.com

Detailed documentation for the tests can be found here: https://jestjs.io/docs/using-matchers

example.com.channels.xml

This file contains a list of channels available at the source.

<?xml version="1.0" encoding="UTF-8" ?>
<channels>
 <channel site="example.com" lang="en" xmltv_id="BBCOne.uk" site_id="bbc1">BBC 1</channel>
</channels>

readme.md

This file contains instructions on how to use this config.

# example.com

https://example.com

### Download the guide

```sh
npm run grab --- --site=example.com
```

### Update channel list

```sh
npm run channels:parse --- --config=./sites/example.com/example.com.config.js --output=./sites/example.com/example.com.channels.xml
```

### Test

```sh
npm test --- example.com
```

The fastest way to create all these files is to use the command:

npm run sites:init --- example.com

Once you are done working on the config make sure the tests pass, the guide downloads and just send us a pull request.

Project Structure

.github/
- ISSUE_TEMPLATE/: issue templates for the repository.
- workflows: contains GitHub actions workflows.
- CODE_OF_CONDUCT.md: rules you shouldn't break if you don't want to get banned.
scripts/: contains all scripts used in the repository.
sites/: contains configurations, channel lists and tests for all sites.
tests/: contains tests to check the scripts.
CONTRIBUTING.md: file you are currently reading.
README.md: project description displayed on the home page.
SITES.md: list of all supported sites and their current status.

Scripts

These scripts are created to automate routine processes in the repository and make it a bit easier to maintain.

For scripts to work, you must have Node.js installed on your computer.

To run scripts use the npm run <script-name> command.

act:check: allows to test the check workflow locally. Depends on nektos/act.
act:update: allows to test the update workflow locally. Depends on nektos/act.
api:load: downloads the latest channels data from the iptv-org/api.
api:generate: generates a JSON file with all channels for the iptv-org/api repository.
channels:lint: сhecks the channel lists for syntax errors.
channels:parse: generates a list of channels based on the site configuration.
channels:editor: utility for quick channels markup.
channels:validate: checks the description of channels for errors.
sites:update: updates the list of sites and their status in SITES.md.
grab: downloads a program from a specified source.
serve: starts the web server.
lint: сhecks the scripts for syntax errors.
test: runs a test of all the scripts described above.

7.4 KiB Raw Blame History Unescape Escape