Copyright: The VideoList 2 file format documentation is copyright © 2005 Rick Murray
Citation: Copyright © 2005 Rick Murray, more details from www.heyrick.co.uk/software/videolist2/


Introduction page
VideoList 2 file format

This help file is aimed at those who wish to read and/or write VideoList2 compatible files within their own software.

I believe in interoperability, so if you implement support for VideoList2 in your own software (even if it is a competitor!), please return the favour by emailing your file specification back to me.

Please select:

The VideoList2 file format

Miscellaneous notes

Data types

Character mapping

The VideoList v1 (original) file format

Contact information

File modification history

Disclaimer (and other notes)

This is the VideoList 2 file format specification.

Version 0.06, 21st November 2005.

Written by Rick Murray.


The VideoList 2 file format
VideoList 2 file format

Original: March Y2K2 (originally based upon the VideoList 1 format, with extensions)

Revised : Oct Y2K5

Note: Revision 1 files are deprecated and not to be used. Upon encountering such a file, VideoList 2 will ask if you wish to have it converted to the Revision 2 format. The differences are shown in mid-blue for reference only.

FILE HEADER

<byte>	Version (0x02)

<halfword>	Number of videos in database

<byte>	Flags:

      Bit 0 : Revision 2 format file - must be set

      Bit 1 : Uses Windows character set - should be set

Bits 2 to 6 : Reserved, should be zero

      Bit 7 : FastLoad data present (currently unsupported)

You should fault the loading of the video data file if any

of the flags have unexpected values. Don't just check for

flags you support, ensure that the others are zero...

The "File created under Windows" flag determines whether

you should use ISO 8859/1 (RISC OS variant) character

mapping, or assume CP-1252 (Windows) character set...

<data>	64 bytes for creator identity.

<data>	4028 NULL bytes to pad to 4K boundary.

VIDEO ENTRY (repeats for each video)

<string>	Video title (32 chars)

<byte>	Flags byte 1:

Bits 0 to 3 - Media type

0 - Video Home System (VHS)

1 - Betamax, BetaSP, DigitalBeta

2 - 8mm, Hi8, Digital8

3 - Digital Video Cassette [H]

4 - VideoCD (VCD) [H]

5 - Super VideoCD (SVCD) [H]

6 - DivX/XviD/3ivX CD-R [H]

7 - Digital Versatile Disc (DVD) [HP]

8 - Other

Usually certain media types, when selected, will

automatically set the Highband and/or Prerecorded flags.

This is shown by an 'H' and/or a 'P' in blue. This is

not a built-in feature of the software, the details of

which flags to auto-set are given in the .dat file.

 Bit 4 - Unused

 Bit 5 - Media is read-only (DVD, VideoCD...)

 Bit 6 - Media is hi-band (S-VHS, Hi8 etc)

 Bit 7 - Media is prerecorded

Revision 1 format files have bits 0 to 2 for the

media type (7 types); revision 2 format files use

bits 0 to 3 to provide up to 15 media types.

<byte>	Filter flag: Is 0 if not matched, 1 if matched. All other

values reserved, is set to '0' prior to any filtering.

This can take any value in the file, as it is cleared and

used internally.

<halfword>	Media length (upper byte is hours, lower byte is minutes)

<halfword>	Time free on media (format as for media length)

<halfword>	Fixed identity number (media ID) - should match video number

<halfword>	Index lookup number This can take any value in the file,

as it is cleared and used internally.

<byte>	Number of programmes currently on this media (max. 20)

<byte>	Unused

<word>	Physical video indexing marker (for future extension)

<word>	Loan check-out time (for future extension)

<word>	Loan return time (for future extension)

<word>	Borrower number (for future extension)

<byte>	Loan duration allowance in days (for future extension)

<3 bytes>	Unused (reserved for future extension data)

[header = 64 bytes]

PROGRAMME DATA (repeats 20 times, once for each programme)

<string>	Programme title (32 chars)

<string>	Programme details (128 chars)

<halfword>	Length (upper byte is hours, lower byte is minutes)

<byte>	Date (day) in lower 5 bits (1-31), bits 5 to 7 are reserved

<byte>	Date (month in lower 4 bits, century from 1900 in upper 4)

<byte>	Date (year, offset from 1900)

<byte>	Flags byte 1:

 Bit 0 - Locked

 Bit 1 – Reserved

 Bit 2 - Reserved for Closed Captioned/Subtitled

 Bit 3 - Programme recorded in Long Play

 Bit 4 - Programme flagged as “To be watched”.

 Bit 5 – Extended data is valid (clear if not defined)

Bits 6 to 7 - Unused

<word>	Genre (extended data):

Byte 0 - Primary genre

Byte 1 - Secondary genre

Byte 2 - Tertiary genre

 0 - No specific genre	 1 - Action

 2 - Adventure	 3 - Adult

 4 - Animation	 5 - Comedy

 6 - Crime	 7 - Documentary

 8 - Drama	 9 - Fantasy

10 - Family	11 - Film noir

12 - Horror	13 - Kids

14 - Music video	15 - Musical

16 – Mystery	17 - Romance

18 - Sci-Film	19 - Short film

20 – Sport	21 - Thriller

22 - War	23 - Western

24 to 255 - Undefined, can be user-altered

Byte 3 - Unused

<byte>	Aspect (extended data):

Bits 0 to 2 - Aspect ratio

0 - 4:3 (standard - 1.33:1)

1 - 14:9 (1.56 pseudo-‘widescreen’)

2 - 16:9 / 1.85:1 (‘Academy Flat’)

4 - 21:9 / 2.35:1 (‘Academy Scope’)

5-7 - Undefined

Bits 3 - 7 - Reserved

<byte>	Primary audio mode (extended data):

Bits 0 to 7 : 	0 - None

1 - Linear mono

2 - Linear stereo

3 - HiFi (PCM) mono

4 - HiFi (PCM) stereo

5 - MPEG audio

6 - Digital mono

7 - Digital stereo (2.0)

8 – Digital surround (5.1)

9 - DTS

10- THX

In revision 1 format files, bits 0 to 3 were for

the primary audio mode, and bits 4 to 7 were for

the secondary audio mode.

<byte>	Secondary audio mode (extended data):

Bits 0 to 7 :	0 - None

1 - Linear mono

2 - Linear stereo

3 - HiFi (PCM) mono

4 - HiFi (PCM) stereo

5 - MPEG audio

6 - Digital mono

7 - Digital stereo (2.0)

8 – Digital surround (5.1)

9 - DTS

10- THX

11- Multilingual same

In revision 1 format files, this byte was used

to provide the "Rating" (as defined below).

The secondary audio mode was defined by bits

4 to 7 of the primary audio mode byte.

<byte>	Rating (extended data):

Bits 0 to 3 – Rating

 0 - No rating

 1 - U          ; Universal

 2 - C          ; Children

 3 - PG-U *     ; PG-U (unoff. ‘10’)

 4 - 12         ; Age 12 or more

 5 - PG-12 *    ; 12, with guidance

 6 - PG         ; Parental Guidance

 7 - 13 *       ; 13+ (unofficial)

 8 - 15         ; 15 or older

 9 - 16 *       ; 16+ (unofficial)

10 - 18         ; 18 or older

11 - 21 *       ; 21+ (EU cert.)

12 – Uncertified

13 to 15 undefined

Bits 4 to 7 - Reserved

In revision 1 format files, the Rating is in the

place of the secondary audio mode (above), and

this byte was unused.

<word>	IMDb identity number

<string>	Channel (22 characters)

[each programme =  200 bytes]

[REPEAT programme data]

[all programmes = 200 bytes x 20 programmes = 4000 bytes]

<data>	Unused, 28 bytes to pad each entry to 4092 bytes in length.

<word>	“#!V!”, to aid automatic recovery.

[REPEAT video data]

[each video = 4096 bytes]


Miscellaneous notes

Bit values shown:

The bit values shown (i.e. audio mode = 4 = HiFi stereo) correlates to the default values provided with VideoList 2 as supplied to the user. However most of these fields are read from files on-disc, so the user is at liberty to change all of these options around. There is currently no way to associate specific sets of options with the video data file, as altering the contents of the .dat files is not an officially supported action.

File format flags byte:

The flags byte determines what 'features' are present in the video data file. When you check this byte, you should not only test for flags of features that you do support, but you should also ensure everything else (i.e. things you do not support or do not know about) are zero.

If the data file flags are unexpected, you should pop up a message similar to the following:

This video data file is a more recent revision than is supported by this version of <appname>. Loading this file may cause incorrect results or possible data loss. Continue loading?

An alternative could be to display something like the above with a warning, and then only permit the file to be read and not written.

Revision 1 file format:

The revision 1 file format (note – this is VideoList 2 revision 1, not the older VideoList 1 format!) was only used with early development versions of VideoList 2. You are, therefore, under no obligation to read this format – and you certainly shouldn't write it!

FastLoader:

VideoList 2 does not (currently) support FastLoader. The index is generated from the database as it is loaded, and tests with ~6,000 videos showed that VideoList 2 didn't fare too badly on a 466MHz Celeron machine... You have the added benefit of the data integrity tests as the index is being generated.

File identification:

There is no header word to auto-ID VideoList 2 data files. There are two things you can do to determine if a file is a VideoList 2 file:

1. The first byte will be 0x02 and the second and third bytes will make a number less than 32,767 (signed integer).

2. The file length will be no less than the number of videos plus one, multiplied by 4096.

3. Look for the "#!V!" marker, every video entry must have one (but first check to ensure that the data file contains videos (i.e. the second and third bytes are non-zero)).

Channels:

The original RISC OS version of VideoList held programme channels as an offset into a table. This proved to be problematic and restrictive. With VideoList 2 the channel is held within each programme and is entered from a pull-down list with a free-form entry. Up to 22 characters (including terminator) can be held. The channel list is provided for convenience. There is no longer any requirement for specific channel data in the data file.

Strings:

Strings are, traditionally zero terminated and padded with zeroes, however it is important to realise that they may also be stored as space-padded without a terminator byte.

Both of these methods must be catered for.

Dates:

The month is held as the lower five bits of the month field. The upper three bits define a century offset from 1900. The year, additionally, is an offset from 1900.

Algorithmically:

actualyear = 1900 + (century * 100) + year

Thus it is IMPORTANT to realise that there is an overlap:

2004 can be century=1 year=4

or:	2004 can by century=0 year=104

The date limit for the century=0 method is 2155 (1900 + 255).

The date limit for the century method is  3655 (1900 + (15 * 100) + 255).

In VideoList (original), the months counted from 0 to 11 as the time was managed using the C ‘tm’ struct. This is no longer the case. Months now count from 1 to 12 as they should.

It is possible to set a date like 31st February in the file as validation is only performed on date entry. Having said this, behaviour with invalid dates is “undefined”.

The special condition where all the date bytes are zero means that the programme is to be “undated”.

IMDb identity:

This is the identity number that may be used to directly view details of the specified film in IMDb.

File sizes:

Each entry is 4096 bytes long, with a 4096 byte header. In order to locate an entry, use the algorithm:

offset = (which_entry * 4096) + 4096

If it helps, the video immediately prior to the entry (except the first entry) will be “#!V!”.

This system allows up to 65,535 videos to be catalogued, a file which would  be 256Mb in size!

Note that VideoList 2 for Windows is restricted to 32,767 videos due to the use of signed integers.


Bytes are eight bit values – 0 to 255.


Halfwords are signed sixteen bit values; the least significant byte appears first in the file.

You should not use numbers greater than 0x7FFF (32,767) as systems that only treat values as ‘signed’ (i.e. VisualBasic) will suddenly believe that you have negative of something!


Words are signed thirty two bit values; the least significant byte appears first in the file.

The special value 0xFFFFFFFF (4,294,967,295) may be used to mean “-1”, but this behaviour is not advised.

The use of numbers larger than 0x7FFFFFFF (2,147,483,647) should be avoided because such numbers may cause problems for systems that use signed integers.


Strings are stored as the sequence of eight bit (byte wide) characters in normal order.

A string may be stored in two possible forms:

1.	Null terminated, and padded with trailing null bytes.

1.	Space-padded with no terminator byte.

It is required that both methods be supported. Perhaps the simplest is to scan through the string converting null bytes to spaces, and then trim tailing spaces.

•	Note that VideoList 2 will also trim leading spaces in strings.

VideoList 2, at this time, uses the Windows CP-1252 (Western European) character set. A bit in the header will allow the selection between this and the RISC OS Latin1 (ISO 8859/1 with extensions) character set; however this is currently unimplemented.


Data is simply a collection of bytes laid out in the format specified.

If no format is specified, assume that the bytes should be null (0x00) bytes.


Data types

Bytes

Bytes are unsigned eight bit values.

Halfwords

Halfword are signed sixteen bit values; the least significant byte appears first in the file.

Note that the use of numbers greater than 0x7FFF (32,767) is not recommended.

Words

Words are signed thirty two bit values; the least significant byte appears first in the file.

The use of numbers larger than 0x7FFFFFFF (2,147,483,647) should be avoided because such numbers may cause problems for a system that uses signed integers.

Strings

Strings are stored as the sequence of eight bit (byte wide) characters in normal order. The string is either padded with null bytes, or with spaces (either of which should be removed upon reloading the string).

Assume, for the time being, that the character set is Windows Western European CP-1252. If the character set bit in the header is unset, the character set will be Acorn Latin1 (ISO 8859/1 with extensions) – however this is currently unimplemented.

Data

Data is simply a collection of bytes laid out in the format specified.

If no format is specified, assume that the bytes should be null (0x00) bytes.


Character mapping

This functionality is currently unimplemented.

VideoList 2 will set the "Windows character set" flag;

and it will assume that it is set (whether it is or not...).

A flag in the header is used to select:

•	RISC OS Latin 1 (ISO 8859/1 with extensions)

•	Windows CP-1252

Except for characters in the range 128–159, both are the same.

Characters in the range 0–31, and 127, are not to be used as on many systems these are "control" characters which perform specific functions. If such characters are encountered, they should be converted to a space (32).

You are expected to correctly read the character set in use, and (if applicable) translate as best as possible. If a character cannot be mapped, it should either be converted to the nearest similar character (i.e. 'Š' becomes 'S') or it should be converted to a space character.

It is acceptable to read in as one character set and save as another, so long as the character set flag is correctly set. Note that this applies to the entire file. You cannot use both character sets at the same time!

UniCode is not supported.

Here is a translation map between Windows CP1252 (ANSI) and RISC OS Latin1 (note that some of these characters may not display correctly in the Help file):

ASCII code	RISC OS	Windows ASCII

128	€	(same)

129	“W with circumflex” 	is not easily available in Windows (Latin Extended-A).

130	“w with circumflex” 	is not easily available in Windows (Latin Extended-A).

131	No character mapping.

132	No character mapping.

133	“Y with circumflex” 	is not easily available in Windows (Latin Extended-A).

134	“y with circumflex” 	is not easily available in Windows (Latin Extended-A).

135	No character mapping.

136	No character mapping.

137	No character mapping.

138	No character mapping.

139	No character mapping.

140	…	133

141	™	153

142	‰	137

143	•	149

144	‘	145

145	’	146

146	‹	139

147	›	155

148	“	147

149	”	148

150	„	132

151	–	(same)

152	—	(same)

153	Third dash type not easily available in Windows, alias as ASCII 150.

154	Œ	140

155	œ	156

156	†	134

157	‡	135

158	“fi ligature” 	is not easily available in Windows (Letterlike Symbols).

159	“fl ligature” 	is not easily available in Windows (Letterlike Symbols).

The following characters are present in the Windows 1252 character set (128-159) but are not supported by RISC OS Latin1:

‚ (130) ƒ (131) ˆ (135) Š (138) ˜ (152) š (154) Ÿ (159)

These characters are available in other RISC OS character sets, but not the default Latin1.

The handling of "fl" and "fi" ligatures is completely application defined. You can either convert to 'f','l' or 'f','i' or you can warn and replace with a dummy character (such as '?').


VideoList 1 file format

This is described here for reference purposes only.

The following software uses type 1 data files:

•	VideoList (the original RISC OS version)

•	VidView (VideoList file viewer for Windows – read only, use VideoList 2 in preference?)

HEADER

         <byte>        Version (0x01)

         <halfword>    Number of videos in database

VIDEO DATA

         [repeats for each video]

           <string>    Video title (32 chars)

           <byte>      Flags (not the same as VideoList 2's method):

                         0 - Type: VHS

                         1 - Type: Beta

                         2 - Type: 8mm

                         3 - Type: DVC

                         4 - Type: Other

                         5 - Unused

                         6 - Video is flagged as 'favourite'

                               (unimplemented)

                         7 - Video is prerecorded

           <byte>      Length (hours)

           <byte>      Length (minutes)

                         Total length = (hours * 60) + minutes

           <byte>      Time free (hours)

           <byte>      Time free (minutes)

           <halfword>  Identity number

           <byte>      Number of programmes currently in this video

           [40 bytes]

           PROGRAMME DATA

           [repeats 20 times, once for each programme]

             <byte>    Programme number (1...20)

             <string>  Programme title (32 chars)

             <string>  Programme details (128 chars)

             <byte>    Length (hours)

             <byte>    Length (minutes)

             <byte>    Channel

             <byte>    Date (day)

             <byte>    Date (month is lower 4 bits; bits 6 & 7 are century)

             <byte>    Date (year (century is recorded along with month))

             <byte>    Flags:

                         0 - Locked

                         1 - Invisible (unimplemented)

                         2 - Programme is a film (unimplemented)

                         3 - Programme is recorded in Long Play (v0.66+).

                         4 - Programme has been 'watched' (v0.87+).

                         It is worth pointing out that the "LP mode" and

                         "watched" bits are the same as VideoList 2, so

                         you can use the same bitmask to read them. The

                         only pitfall is that VideoList 1 stores a flag

                         for watched while in VideoList 2 it is a flag

                         for unwatched. You'll need to invert it...

           [end repeat; 168 bytes * 20 = 3360]

         [end repeat]

         Each record is 3400 bytes long. In order to find a record for

         loading, we use the algorithm "(which * 3400) + 3".

IMPORTANT:

•	Flag bit 4 is “watched” in VideoList 1. The corresponding bit is “not watched” in VideoList 2.

•	The century only has three bits, so is in the range 0 – 7 rather than 0 – 15. Additionally, the bit offset is different.

•	Certain flags are no longer supported (video ‘favourite’ and programme ‘invisible’). You will not encounter these as they were never implemented.

•	Long Play first appeared with version 0.66; ‘watched’ first appeared with version 0.87.

•	As with VideoList 2, the ‘Long Play’ flag changes the granularity of the times to 2-minute units.

•	ALL STRINGS IN VIDEOLIST 1 FILES ARE NULL TERMINATED. SPACE-PADDED STRINGS ARE NOT SUPPORTED.


Contact information

The VideoList 2 website is currently:

http://www.heyrick.co.uk/software/videolist2/

You can email me at:

heyrick@merseymail.com

Please note that I only have access to the Internet one afternoon a week at the local library, I tend to collect mail one week and send replies the following week; so an immediate response is simply not possible.

Additionally, you should not send attachments as my provider removes most non-image attachments from messages unless I tell it not to (on a person-by-person basis). If it is imperative that your zip file reach me with your message, then upload it to some webspace and write the URL to it at the top of your message (I always read the first couple of lines).


The version numbers currently allocated are:

•	“ 1” for VideoList files.

These are loaded and saved by the original RISC OS VideoList.

These are loaded by the Windows VidView viewer.

VideoList 2 can export this type of file, if required.

•	“ 2” for VideoList 2 files.

These are loaded and saved by VideoList 2.

VideoList (original) can export these using an undocumented method (export ALL as VideoList, and hold down ALT when dragging out the icon). Note that files exported in this way are technically 'broken' (very early file format, revision zero!) and will probably need a small amount of processing before use with VideoList 2 or similar...


Both the RISC OS original and the Windows VideoList 2 have an arbitrary limitation on the number of videos that can be displayed. This limitation is 9,999 videos, though this is purely a visual thing, making the software support more videos is not difficult – indeed VideoList 2 will prompt you if you wish to continue though it may look slightly incorrect on-screen.

Of, potentially, greater problem is using a half-word for the index value. Visual Basic 5 (that which VideoList 2 for Windows is written in) treats values as “signed” with apparently no “unsigned” option. This could cause problems with more than 32,767 videos.


Though it is not official, the format of this string is:

Created by <programname> v<majorversion>.<minorversion> [optional comment]

For example:

Created by VideoList v0.91

and:

Created by VideoList 2 v2.00r56 [for Microsoft Windows]


This data is all blank, currently unallocated. Some filing systems work best with read/write chunks that are at multiples of 4096 bytes, and the natural block size of a VideoList 2 file is 4096 bytes, hence this has been applied to the header.


Historically, the string “<video deleted>” marks a deleted video.

This system is retained within VideoList 2, the main difference being that you are no longer shown deleted videos.

Upon adding a new video, the “Next” button allows you to step through the available deleted videos and the logical ‘next’ in sequence.

Consequently, you cannot assign the title "<video deleted>" to any videos.


The read only attribute is not (currently) directly editable within VideoList 2. It is set by media types with the “!R~” marker in the media.dat file (i.e. DVD, VideoCD, etc).

It is not implemented as I do not see how a read-only flag would provide any benefit to the end-user.


The high band attribute is editable within VideoList 2, and it is also set/unset according to the “!H~” marker in the media.dat file.


The prerecorded attribute is editable within VideoList 2 and is also set/unset by the “!P~” marker in the media.dat file.

The difference between a pre-recorded and not prerecorded media is that the “free space” displays are omitted from pre-recorded media; and also the length(s) of prerecorded media extends as programmes are added.


The number of minutes is determined by:

( (((value >> 8) AND 255) * 60) + (value AND 255) )

In VideoList (original), the maximum length of any media was 660 minutes (11 hours). This limit has been increased to 999 minutes (16 2/3 hours).

It is possible to record lengths of up to 15,555 minutes (259¼ hours). If this is seen as necessary, please contact me.


Every video has a unique ID number, starting from 1 and running sequentially.

Deleted videos as marked as having the title “<video deleted>”, and upon adding a new video, it is recommended that the “first available slot” algorithm is used, to fill in these blanks.

Deleted videos are not completely erased from the video database primarily due to time concerns. Videos can be deleted, and deleted videos replaced, without structural changes to the file. The alternative would be to either shift every following video for every insert/delete operation or to maintain a rule such as “allow 10% fragmentation”, both of which are less flexible to my mind.

Put it this way, the largest the video database can be is around 256Mb. Modern computers typically can with harddiscs in the order of 20 to 160Gb. Are you willing to trade up the loss of ¼Gb worst case instead of faster operation?


This is used in the primary index (the video database lookup) and the secondary index (the on-screen display) to keep track of the relationship between the two. This is especially important during filter operations, and also when manipulating a video list with non-contiguous (i.e. some deleted videos) entries.

Any data stored in this location in the actual data file is ignored, and whether or not such data is written back to the file upon updates is implementation specific.


You can have from zero to twenty programmes on any given media.

On an E240 in LP mode (eight hours), this would equate to twenty programmes of 24 minutes each, which is seen as sufficient. If this should prove to be restrictive (it has not to me, in several years of using VideoList), then we can look to increasing the number in a future file format.


This data is reserved for a future expansion to the VideoList product range, which will provide facilities to tie the video database in with the running of a small video shop.

index marker	The numerical ID as held on your own database.

check-out	The time when the video was taken out.

return	When the video should be returned by.

borrower	The numerical ID of the video borrower.

duration	The duration of the loan – zero means “use default”.

(this is so older tapes can have a longer loan time than newer tapes)

The time formats have not yet been decided.


Like the video lengths, the programme lengths are in the form:

( (((value >> 8) AND 255) * 60) + (value AND 255) )


Bits 0 to 4 define the day of the month (1 to 31).

Bits 5 to 7 are unused.

If all of the time values are zero, the programme is marked as “undated”.


Bits 0 to 3 define the month (1 to 12).

Bits 4 to 7 define the century offset from 1900 (0 to 15).

Note that VideoList (original) stored dates in the range 0 to 11, though this will only appear in type 1 files.

If all of the time values are zero, the programme is marked as “undated”, but VideoList 2 only checks to see if the day is zero.

•	Note that you should assume that a programme is undated if the day is zero. Currently all fields are zeroed, but in the future it may be that "day=0 and year=special value" for additional forms.

•	If the month should be zero and day/year is not zero, this will most likely have occurred due to an original format VideoList file translated incorrectly.
The VideoList 2 behaviour is to silently add '1' to make the month 'January'. It would seem logical to add '1' to every programme month in that case, but this presents its own problems.
As VideoList 2 data files containing month=0 with day/year=non-0 is strictly a 'broken' value, you are free to implement any form of handling you feel necessary, though I suggest against the following:

1.	Refusing to load the file. It isn't a critical problem, handle it.

1.	Prompting or warning for every occurrence. If the user has eighty things recorded in January in her broken file, this could mean 80 warnings. How annoying!
You could warn once and remember what action the user takes. It the event occurs again, ask if they'd like to be warned for further occurrences, or if they'd like it to be auto-fixed (VideoList 2 may do this, later on).

Remember – this is, strictly speaking, bogus data. You should 'cope' but you don't need to go unduly out of your way...


This gives the year offset from 1900.

Alone, it provides a range of 1900 to 2155, but it is expected to be used alongside the century offset for a date range of 1900 to 3655.

The year 3655, I believe, is later than the date-rollover on most PCs ... like people will even know what Windows is some 1,650 years from now! Do you know what happened some 1,650 years ago? The year would be AD450. Ancient Rome still ruled Europe. The Dark Ages would just be starting. The Franks were unimportant, that happened later. Mayans still hung out in South America. This age was before Charlemagne, before Islam (that was 611), before the main expansion of Christianity (in 476), before books, polyphonic music, Richard the Lionheart and the Crusades, and a billion other things. So, to think that in 1,650 years from now we'll still be sitting at PCs running versions of Windows with which we'll enter in details of video tapes and DVDs is a remarkably silly prospect...

...but just in case we are... VideoList 2 will be there for you.

Just don't expect any end-user support for the roll-over to the year 3656 'cos I'll be very very very dead by then.

Please refer to the “ Dates” notes for more information.


A locked programme cannot be deleted until it is unlocked.


In the primary index, this flag is used to mark entries that match the filter criteria. After the filter has scanned all of the entries, the secondary index will be created from those entries with this flag set.

Any data stored in this location in the actual data file is ignored, and whether or not such data is written back to the file upon updates is implementation specific.


This attribute is not currently editable.


A side effect of ‘Long Play’ is that programme lengths work in units of two minutes.

Internally, the regular (minute) value is stored, and the LP flag instructs VideoList 2 to multiply this by two.


If this flag is unset, the extended data will be ignored.


The genres selection list is alphabetically sorted, therefore the user can add custom genres to the end of the list (currently entries 24 to 255 are free).

If the user decides to completely alter the genres list (perhaps “Children” instead of “Kids” (though I do like the way “Kids” appears between “Horror” and “Music video”, is this not somehow appropriate?)), they should do this before any videos are given genres, as later modifications will affect existent videos.

The filter system will look at all three genre types when trying to make a match. However be aware that if two genre types are specified, it works on an AND principle – for example “horror” and “comedy” would return something like “Attack of the Killer Tomatoes” which is horror and comedy (and ridiculous, but that isn’t a genre), but it will not match something like “Day of the Triffids” which is “horror” and “sci-fi”.

If you are inclined to “horror”, “disaster” and “sci-fi” movies, you might like to include decades as genres which can be programmed into the tertiary genre setting, thus “Night of the Comet” could be “Sci-fi”, “Horror”, and “80s”.


The aspect ratios are:

•	4:1 (or 1.33:1) which is the aspect of a normal television set.

•	14:9 (or 1.56:1) which is the ‘pseudo widescreen’ designed to give acceptable results on normal and widescreen televisions.

•	16:9 (or 1.85:1) which is the format of a widescreen television. This is also known as “Academy Flat”.

•	21:9 (or 2.35:1) which is the cinema aspect. It appears slightly letterboxed on a widescreen television, and particularly letterboxed on a normal 4:3 television. This is also known as “Academy Scope”.

There is no marking for whether a given programme is letterboxed or anamorphically stretched, as many devices offer an option of either of these. Additionally, some devices also offer “pan and scan” which shows part of a widescreen frame in full size on a 4:3 television.

Occasionally you will encounter a DVD with a non-standard aspect. “Backdraft”, for example, claims to be 2.02:1.Here, you can either add to the aspect.dat file, or you can do the sensible thing and assume one of the normal aspects (I’d be inclined to reduce 2.02:1 to 1.85:1, hence 16:9).


The secondary audio mode is for media that supports different audio modes. This is normally intended for DVDs which often offer Digital surround (5.1) and DTS; however you could apply the logic to VHS tapes that offer linear mono and Hi-Fi stereo.

The “Multilingual same” option is for DVDs which offer the same sort of soundtrack (5.1, etc) in a variety of languages.

It isn’t always sanely possible to note which soundtracks are offered by DVDs. Some offer the primary language(s) in 5.1, perhaps DTS too, and the secondary languages in 2.0, along with various commentary tracks. Some go overboard and include the main audio in MPEG, 2.0, and 5.1 – along with other languages and things. Why? Don't ask me!


The default Ratings table is based upon the British BBFC, with a number of additional (mostly Americanised) entries. It is suggested that users outside of England replace this with their own ratings systems before adding videos, if they feel these ratings are not suitable.

Alternatively, they could modify the table so long as they do not alter the order once programmes have been rated. For example, France has “Tous Publics” (like "U") and “Interdit moins de 12 ans” (like "12") etc.


This is the number of the movie as referenced by IMDb at:

http://www.imdb.com/

In order to ascertain the IMDb number, look up the movie you wish to reference in IMDb  Then look at the URL bar, it will say something like:

http://www.imdb.com/Title?0123456

The number at the end is the IMDb ID number. Store this within VideoList 2 and it will go directly to the information for the specified movie.

If no ID number is recorded, VideoList 2 will try using the movie title.


The channel list is provided as a convenience. You can also enter channel names in free form, and as the name is stored with each programme, it is possible that every programme could have a different channel.


VideoList 2 is reliable and does not mangle the database file (unless there is a physical hardware issue involved). Changes are written out automatically so nothing is cached to be written “later”. Also, VideoList 2 maintains two recovery backups. One is taken as the program starts and the other prior to modifications being made.

However, things could still go wrong, such as a transfer by floppy, modem, or internet that is corrupted. Disc error, disc full, or some other problem. In these situations, VideoList 2 will report problems with specific videos which can be cured either by updating the affected video(s) (perhaps with corrections), or by deleting and recreating the affected video(s).

In more severe cases, the database itself may have ‘lost’ some data so things are no longer aligned to 4096 byte boundaries. The recovery marker “#!V!” will permit VideoList 2 to search for these markers and attempt to rebuild a damaged video file.

Basic file correction is supported in the "Strict verification" option is enabled (in Settings).

If you wish to 'recover' from a previously-created backup, note that these have the extension ".vbi" (initialisation backup) and ".vbp" (pre-modification backup). Simply remove the damaged ".vlf" file and copy one of the backup files in it's place.

VideoList 2 does not currently provide support for files that do not have the recovery marker in the correct position (i.e. a truncated start).

However, it is possible to recover such a file with a short BASIC or C program, as follows:

•	The ID number relates to the actual 'number' in the file. ID 7 is the seventh video.
So create a file with null bytes (0x00) up to the start of what you do have. The video should begin at a 4K boundary.

•	Set the first byte of the file to 0x02.

•	Set the second and third bytes of the file to a signed integer describing how many videos there are in your file (including the 'missing' ones).

•	Set the fourth byte to 0x03 (Revision 2, Windows character set).

Then load it. VideoList 2 will probably complain about a LOT. But after a while (depending on missing videos), it will load up... You can then renew any data that is missing.


Easter egg
EASTER EGG!

Yay! You found the Easter Egg!


Easter eggs are little things inserted by the programmer(s) at design time. Some may actually be useful, but most are humourous in some way. Some, indeed, are things of legend.

Generally the number of easter eggs relate directly to how bored and/or depressed the programmer is. My life is pointless and I can’t concentrate on anything for more than a few minutes, so you’ll find a number of eggs in my software… :-)


Disclaimer (and other notes)

The main index page of this help file details the date when this document was last modified.

If this date was a while back, it could be worth checking

the support website to see if a newer version is available.

Disclaimer

This information is provided in good faith, but is not guaranteed to be complete nor accurate. E&OE.

What you see documented here is the file specification followed by my VideoList 2 software.

The base version of the file format is the VideoList 2 revision 2 format. All software that claims to be VideoList 2 compatible must be able to fully and correctly read and write (if applicable) this format.

There is no obligation to be able to read VideoList 1 files.

VideoList 1 (for RISC OS) generates incorrect VideoList 2 files, as the specification has expanded quite a lot from the original specification in 2002. This is not considered a non-compliance as VideoList's ability to export such files was an undocumented feature and it predates VideoList 2!

In case of problem or ambiguity, your sole remedy is to contact me for clarification.

This disclaimer only applies to the specification document that you are currently reading.

It does not apply to the software product, nor any other documentation relating to the software

product, both of which should be covered by separate licences described elsewhere.

Variances

Please note that, from time to time, other undocumented flags may be inserted into some of the bytes marked unused. Unless the software version notes describe extensions to the base format, you should ignore the settings of any of these additional flags with the exception of the file format flags. It is best if you preserve them if possible, but not mandatory that you do so.

As far as possible, such test features will be allocated so as not to affect other known extensions.

Format extensions

Extensions and modifications to the base format will only become ‘official’ once the specification has been revised and a new document released.

I, the author, will be the arbitrator of such modifications. Simply contact me with details of proposed modifications, though note the following:

•	I will not look favourably upon product-specific values. If you wish to add a halfword for the implementation of a “video counter” (the old unreliable method), that is fine. If you add the comment “only for use by blahblah”, then it will be rejected.

•	This is an open format. Data cannot be allocated “for the use of blahblah” with no further specifications unless I have agreed to a specific extension-in-testing that you do not wish to have documented until the format has been finalised.

•	Proprietary enhancements will not be permitted.

•	By adding any form of enhancement to the VideoList 2 format (even if you do not register it), you agree to waive any rights to royalties, software patents, etc.

•	Now a note for the more megalomaniacal American software companies: It is forbidden to apply for a patent for any part of the VideoList 2 specification, including concepts, algorithms, and ideas expressed within. Software cannot be patented within the European Union, and as such any patents taken out on any part of the VideoList 2 file format (or the ideas/algorithms expressed within) will be ignored. This includes within the United States regardless of what your patent application may say to the contrary because it actually says above that this stuff should not be patented. Period.

•	By defining an enhancement, you agree that other VideoList 2 compatible software may utilise these enhancements (i.e. if you add a tape counter value, I could add a tape counter into VideoList 2, that sort of thing).

•	All enhancements must be backwardly compatible unless it is totally impossible to make them so.

•	If you think that most of these terms say exactly the same thing, only worded in different ways, you may be right...

The older (VideoList 1) format

It is recommended that VideoList 2 software also be capable of at least reading the older file format, though the implementation of such is left entirely at your discretion.

Supplying this help file

It is mandatory that this specification is supplied with any software supporting this file format, however please be aware that you will require my permission beforehand.

This is primarily a formality to ensure you will be using and distributing the latest version of this specification, though measures may be taken against any person or organisation that “goes ahead and does it” without bothering to ask first.

You can open this file directly by calling:

CommonDialog1.HelpFile = App.Path & "\Data\File2fmt.hlp"

CommonDialog1.HelpCommand = cdlHelpContents

CommonDialog1.ShowHelp

in VisualBasic. The same sort of idea in other languages…


Modification history

2002/03/04 (Rick Murray)

First draft of the VideoList 2 specification created.

2002/03/06 (Rick Murray)

Revised the specification to include audio type and aspect information.

2004/09/04 (Rick Murray)

Split the audio and aspect information into separate bytes. Altered the possible values of most of these such options to closer reflect what is likely to occur (i.e. “Linear mono or stereo” instead of separate entries, they both offer the same lack of quality…). Also extended the genres to be a word value, using the third byte for a third genre. The fourth byte is not currently assigned.

2004/09/13 (Rick Murray)

Windows Help file finished.

It’s be nice if Word could create RTF files with matching numbers of opening and closing braces, though luckily the help compiler copes with it – perhaps it is used to Word’s lossage?

2004/10/01 (Rick Murray)

Document revised to clarify a few things and also to extend the string format to include space-padded strings (it is easier to change the format than to get VisualBasic 5 to act sanely; fixing this space-padded nonsense in C is pretty trivial).

2004/10/11 (Rick Murray)

Document revised to change the filter flag from programme-specific to video-specific.

2005/05/26 (Rick Murray)

Document revised to add 'revision 2' changes – primarily more media types, more audio types; thanks to suggestions proposed by Ewen Cathcart.

2005/10/27 (Rick Murray)

Updates and tweaks prior to 'revision 2' implementation.

2005/11/21 (Rick Murray)

Final editing and tidying up prior to product release.

The default character set is now Windows CP-1252; and integers/words are now to be considered "signed". This is for better compatibility with the Windows version of VideoList 2 as it is not terribly likely that a RISC OS version will be produced.

The following people and/or companies have made extensions to the base specification (click link for specifics):

•	Ewen Cathcart (2005/05/26)


File format modification 2005/05/26
File format modification proposal: 2005/05/26

Ewen Cathcart suggested the addition of digital media formats such as DivX and 3ivX due to a growing number of people that make up their own media. In effect, this also requires additional audio type options...

History:

Proposed	2005/05/26 (by email)

Added to specification	2005/05/26

Implemented in software	2005/11/17 v2.00r54