Guide XML: Structure, Timeslots, and Program Listings

guide.xml is the data layer for Television Simulator ‘99. It is a static XML file that carries every channel name, programme listing, on-screen notice, and ad panel shown by the Prevue guide. The file is fetched once at startup — after the YouTube IFrame API is ready — parsed into a jQuery object, and stored globally so every channel class can query it without making additional HTTP requests.

Loading Sequence

After the youtubeReady event fires, TV.startUp() issues a jQuery AJAX GET request, parses the raw response with $.parseXML, and wraps the result in jQuery for easy traversal:

document.addEventListener('youtubeReady', () => {
    $.ajax({
        type: 'GET',
        url: 'data/guide.xml',
        dataType: 'xml',
        complete: (data, status) => {
            window.guideData = $($.parseXML(data.responseText));
            var defaultChannel = guideData.find('channel[watchable][default]').attr('number');
            if (undefined != defaultChannel && null != defaultChannel) {
                this.showChannel(defaultChannel);
            }
        }
    });
});

After this point window.guideData is available to any code in the page. Channel classes receive guideData as a constructor argument (stored as this.guideData), but in practice Channel12.show() reads the global guideData variable directly rather than using this.guideData.

The channel launched at startup is the <channel> element that carries both the watchable and default attributes. In the default guide.xml that is channel 12 (PRV). Removing either attribute from that element will prevent the simulator from loading a default channel.

Document Structure

The root <guide> element contains three kinds of children:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<guide>
    <videos>…</videos>
    <ads>…</ads>
    <channel number="…" name="…">…</channel>
    <!-- more <channel> elements -->
</guide>

`<videos>`

Reserved for future use. Currently holds one <video> element with an id attribute referencing a YouTube video ID, but no channel class reads from this section at runtime. Channel12 hardcodes its video ID (9NSVU4Gv_wA) directly in script.js rather than sourcing it from the XML.

<videos>
    <video id="oemoqEuJdFE" />
</videos>

`<ads>`

A list of <ad> elements displayed in the left-hand panel of Channel 12. Each ad contains arbitrary HTML and a duration attribute (in seconds):

<ads>
    <ad duration="30">
        <p>HBO<br />12 months $10.95 / mo.</p>
        <p>Sign up today!<br />1-800-555-9485</p>
    </ad>
    <ad duration="30">
        <p>Showtime Value Package<br/>Showtime, Sundance &amp; Movie Channel</p>
        <p>$10.95 / mo.<br/>1-800-555-9485</p>
    </ad>
</ads>

Channel 12 reads every <ad> element into this.adList and rotates through them using nextAd(). The duration value defaults to this.defaultAdDuration (30 seconds) if the attribute is absent.

`<channel>`

The bulk of the file consists of <channel> elements, each representing one row in the program grid.

Channel Attributes

Attribute	Required	Description
`number`	Yes	Channel number shown in the grid and used as the `TV.showChannel` argument.
`name`	Yes	Short station callsign shown below the channel number (e.g. `KCBS`, `PRV`).
`watchable`	No	Presence (no value needed) marks the channel as one the viewer can tune to.
`default`	No	Presence marks this channel as the one loaded automatically at startup.
`noticeonly`	No	Presence causes Channel 12 to skip rendering a channel row; only its `<notice>` elements are shown.

A minimal watchable channel looks like this:

<channel number="12" name="PRV" default="default" watchable="watchable">
    <listing timeslot="1" type="1" data2="0" data3="0" data4="0">Prevue Channel</listing>
</channel>

A channel with a public notice:

<channel number="3" name="KCBS">
    <notice>The Greenhill County public offices will be closed to the public Monday, May 3, 1999 for renovation.</notice>
    <listing timeslot="19" type="1" data2="22" data3="0" data4="0">News</listing>
    <listing timeslot="20" type="1" data2="34" data3="0" data4="0">Bold and the Beautiful</listing>
</channel>

The Timeslot System

Timeslots are index numbers, not absolute clock times. The simulator does not look at the actual time of day to determine which programme is “on now”. It uses curTsStart (set to 19 in Channel 12) as the left-most visible column and renders the two subsequent half-hour slots alongside it.

Each half-hour of the day maps to a timeslot index:

Timeslot	Time of Day
0	12:00 AM (midnight)
1	12:30 AM
2	1:00 AM
…	…
18	9:00 AM
19	9:30 AM
20	10:00 AM
33	4:30 PM
38	7:00 PM
48	12:00 AM (next day)

A <listing> with timeslot="19" starts at 9:30 AM. If the next listing for that channel is at timeslot="21" (10:30 AM), the programme spans two half-hour cells and will be rendered with colspan="2" in the grid.

`getFirstListing()` Logic

Channel 12 finds the correct listing for a given display column by walking backwards from the target timeslot until it finds a match:

getFirstListing(listings, timeslot) {
    var out;
    var listingTss = $.map(listings, (listing) => {
        return parseInt($(listing).attr('timeslot'));
    });

    for (var i = timeslot; i > -1; i--) {
        var index = $.inArray(i, listingTss);
        if (index !== -1) {
            out = listings[index];
            break;
        }
    }

    return out;
}

This handles programmes that begin before the visible window — if a movie started at timeslot 17 and the grid opens at 19, the movie’s listing still appears in the first column.

`<listing>` Attributes

Attribute	Description
`timeslot`	Half-hour index at which the programme starts.
`type`	`1` = regular programme; `9` = alternate style; `movie` = movie (rendered with a CSS class).
`data2`	Duration category code used in the original Prevue data format; not directly rendered.
`rating`	Optional content rating string (e.g. `TV-PG`, `G`, `PG-13`) displayed in the listing cell.
`continuous`	Presence indicates the programme continues from the previous day.
`noticeonly`	Presence on a `<channel>` (not a listing) causes the row to be skipped entirely except for its notices.

The element’s text content is the programme title and is used as the cell’s HTML via .html():

generateListing(listing, colspan, timeslot) {
    const html = $('<td>').addClass('listing').html(listing.html());
    if (colspan) html.attr('colspan', colspan);
    if (listing.attr('type') === 'movie') html.addClass('movie');
    return html;
}

`<notice>` Elements

<notice> children of a <channel> are rendered as full-width rows with a red background, spanning all four columns of the grid:

$(ch.find('notice')).each((i, notice) => {
    const noticeRow = $('<tr>');
    noticeRow.append(
        $('<td>').addClass('notice').attr('colspan', 4).html($(notice).html())
    );
    this.listingGrid.append(noticeRow);
});

Example XML that produces a notice row:

<channel number="3" name="KCBS">
    <notice>The Greenhill County public offices will be closed to the public Monday, May 3, 1999 for renovation.</notice>
    <listing timeslot="19" type="1" data2="22" data3="0" data4="0">News</listing>
</channel>

Channels in the default guide use notices to display public announcements or other informational messages above the channel row.

Representative Sample

Below is an abbreviated but complete slice of guide.xml showing each element type in context:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<guide>

  <videos>
    <video id="oemoqEuJdFE" />
  </videos>

  <ads>
    <ad duration="30">
      <p>HBO<br />12 months $10.95 / mo.</p>
      <p>Sign up today!<br />1-800-555-9485</p>
    </ad>
  </ads>

  <!-- Watchable default channel — loaded at startup -->
  <channel number="12" name="PRV" default="default" watchable="watchable">
    <listing timeslot="1" type="1" data2="0" data3="0" data4="0">Prevue Channel</listing>
  </channel>

  <!-- Regular channel with a notice and multiple listings -->
  <channel number="3" name="KCBS">
    <notice>The Greenhill County public offices will be closed Monday, May 3, 1999.</notice>
    <listing timeslot="19" type="1" data2="22" data3="0" data4="0">News</listing>
    <listing timeslot="20" type="1" data2="34" data3="0" data4="0">Bold and the Beautiful</listing>
    <listing timeslot="33" type="1" data2="34" data3="0" data4="0">Entertainment Tonight</listing>
  </channel>

  <!-- Movie listing -->
  <channel number="6" name="TBS">
    <listing timeslot="33" type="movie" data2="1" data3="5" data4="0" rating="TV-PG">
      ( 7:05) "A Christmas Story" (1983) Peter Billingsley, Darren McGavin. (1 hr 38 min)
    </listing>
  </channel>

  <!-- Notice-only entry — no channel row rendered, only the notice text -->
  <channel noticeonly="noticeonly">
    <notice>TS99 Networks, Inc</notice>
  </channel>

</guide>

Get Started

Core Concepts

Customization

Reference

Guide XML: Structure, Timeslots, and Program Listings

Loading Sequence

Document Structure

`<videos>`

`<ads>`

`<channel>`

Channel Attributes

The Timeslot System

`getFirstListing()` Logic

`<listing>` Attributes

`<notice>` Elements

Representative Sample

Build docs developers (and LLMs) love

Get Started

Core Concepts

Customization

Reference

Documentation Index

​Loading Sequence

​Document Structure

​<videos>

​<ads>

​<channel>

​Channel Attributes

​The Timeslot System

​getFirstListing() Logic

​<listing> Attributes

​<notice> Elements

​Representative Sample

Build docs developers (and LLMs) love

Loading Sequence

Document Structure

`<videos>`

`<ads>`

`<channel>`

Channel Attributes

The Timeslot System

`getFirstListing()` Logic

`<listing>` Attributes

`<notice>` Elements

Representative Sample