Writ

Introduction

Ogg Writ is a text phrase codec. While its primary purpose is to embed subtitles or captions in a Theora stream, its design makes it useful for many other purposes. It could provide lyrics to song encoded in Vorbis, a transcript to a political debate encoded in Speex, or even incorporate a live chat session as part of a continuous video stream.

One of the unique aspects of Writ is its discontinuous nature, that is, unlike other Ogg codecs the granules for which seperate packets effect may overlap. See the Granules and Muxing section below for how this works.

SVN

Current Ogg Writ development is on Xiph SVN as /trunk/writ/. It's being developed to use libogg2, so you'll need both to work on it. The reference encoder and decoder are available as part of the py-ogg2 package which is available on Xiph SVN as /trunk/py-ogg2/.

This is a (near final) working draft of the spec
Writ has been designed so that encoders/decoders can support a bare minimum and be fully compatable with future subversions. Each subversion adds a new feature, some building on others, adding a new header packet and likely a new field to each body packet.

Decoders should ignore header packets beyond what they were written to support and also ignore extra fields in data packets beyond their current version. This allows new features to be added without requiring that all software, or even most software, to support them.

We will be conservative about adding future subversions.

Header Packet 0 (BOS, 16 bytes):
 0x00                                   ( 8 bit Header 0)
 "writ" (LSB 0x74697277)                (32 bit codec identification)
 version                                ( 8 bit unsigned int, 0 = Alpha)
 subversion                             ( 8 bit unsigned int)
 granulerate_numerator                  (32 bit unsigned int)
 granulerate_denominator                (32 bit unsigned int)

Data Packet (each):
 0xFF                                   ( 8 bit 0xFF = data packet)
 granule_start                          (64 bit signed integer)
 granule_duration                       (32 bit unsigned integer)
 text_length                            ( 8 bit unsigned integer)
 text_string                            (variable-length UTF-8 string)


<B>Subversion 1 adds multiple language support</B>

Header Packet 1 (Language Definition, 8+ bytes) :
 0x01                                   ( 8 bit Header 1)
 "writ" (LSB 0x74697277)                (32 bit codec identification)
 num_languages                          ( 8 bit unsigned int)
 [repeated 1+num_languages times] :
   language_length                      ( 8 bit unsigned int)
   language_string                      (0+language_length rfc3066)
   language_desc_length                 ( 8 bit unsigned int)
   language_desc_string                 (0+language_desc_length UTF-8)

Data Packet (each):
 0xFF                                   ( 8 bit 0xFF = data packet)
 granule_start                          (64 bit signed integer)
 granule_duration                       (32 bit unsigned integer)
 [repeated num_languages times] :
   text_length                          ( 8 bit unsigned integer)
   text_string                          (variable-length UTF-8 string)


<B>Subversion 2 adds text window support</B>

Header Packet 2 (Window Definition, 10+ bytes) :
 0x02                                   ( 8 bit Header 2)
 "writ" (LSB 0x74697277)                (32 bit codec identification)
 location_scale_x                       (16 bit unsigned int)
 location_scale_y                       (16 bit unsigned int)
 num_windows                            ( 8 bit unsigned int)
 [if (window_num > 0) repeated window_num times] :
   location_x                           (variable length, see below)
   location_y                           (variable length, see below)
   location_width                       (variable length, see below)
   location_height                      (variable length, see below)
   alignment_x                          ( 2 bit alignment, see below)
   alignment_y                          ( 2 bit alignment, see below)

Data Packet (each):
 0xFF                                   ( 8 bit 0xFF = data packet)
 granule_start                          (64 bit signed integer)
 granule_duration                       (32 bit unsigned integer)
 [repeated num_languages times] :
   text_length                          ( 8 bit unsigned integer)
   text_string                          (variable-length UTF-8 string)
 [if (window_num > 1)] :
   window_id                            ( 8 bit unsigned integer)


<B>Example Stream</B>
 Header Packet 0
  version 0
  subversion 2
  granulenum 1
  granuledom 1
 \x00writ\x00\x02\x01\x00\x00\x00\x01\x00\x00\x00

 Header Packet 1
  num_languages 2
   Language 0:
    language en
    language_desc English
   Language 1:
    language es
    language_desc Spanish
 \x01writ\x01\x02en\x07English\x02es\x07Spanish

 Header Packet 2
  location_scale_x 4000 (12 bits)
  location_scale_y 270  ( 9 bits)
  num_windows 2
   Window 0:
    location_x 1
    location_y 2
    location_width 3
    location_height 1
    alignment_x 3 (Full)
    alignment_y 3 (Full)
   Window 1:
    location_x 5
    location_y 6
    location_width 7
    location_height 1
    alignment_x 3 (Full)
    alignment_y 3 (Full)
 \x02writ\xa0\x0f\x0e\x01\x02\x01\x20\x60\x00\x02\x7c\x01\x18\x38\x80\x00\x0f

 Phrase Packet:
  granule_start 5
  granule_duration 10
  Language 0: "Hello World!"
  Language 1: "Hola, Mundo!"
  window_id 0
 \xff\x05\x00\x00\x00\x00\x00\x00\x00\x0a\x00\x00\x00\x0cHello World!\x0cHola, Mundo!\x00

 Phrase Packet:
  granule_start 12
  granule_duration 15
  Language 0: "It's a beautiful day to be born."
  Language 1: "Es un día hermoso para que se llevará."
  window_id 1
 \xff\x0c\x00\x00\x00\x00\x00\x00\x00\x0f\x00\x00\x00\x20It's a beautiful day to be born.\x26Es un d\xeda hermoso para que se llevar\xe1.\x01

Granules and Muxing

Granulepos in Writ (as well as future discontinuous codecs) will be by start time, not end time, that the data in a given page is tagged for. This greatly simplifies this specification (see the old method below).

All Writ phrases will be provided at and given the granulepos of their start time, ordered by their start time within the logical bitstream.

Phrase packets with long durations should be repeated in the logical bitstream at regular intervals to ensure that a player seeking to the middle of their duration will still see them. These packet copies will be identical to their original, including the start and duration fields, the granulepos of the page they reside on will be incremented for each copy to place it forward on the logical bitstream.

No two phrases can start on the same granule. On decoding, each packets' start granule is checked against already known packets. If a match is found the new packet is ignored. This prevents phrase copies from being interpreted as new phrases.

Seeking Example


Here is a timeline (granule numbers at top, read down) of a sample stream:

                        <- Granules ->
0000000000111111111122222222223333333333444444444455555555556666666666
0123456789012345678901234567890123456789012345678901234567890123456789
 ___________  ____________  ____________  ____________  _____________
|_Vorbis____||_Vorbis_____||_Vorbis_____||_Vorbis_____||_Vorbis______|
 ____________________   ____________________________________
|_A____________>_____| |_D____________>______________>______|
     _________      ___    __________     ___________
    |_B_______|    |_C_|  |_E________|   |_F_________|

 (note: these have been seperated vertically for easy viewing only)

Packet  Granule Description
 V H0   0       Vorbis Header 0x01 (page by itself)
 W H0   0       Writ Header 0 (page by itself)
 V H1   0       Vorbis Header 0x03
 V H2   0       Vorbis Header 0x05
 W H1   0       Writ Header 1 (Language Defs)
 W H2   0       Writ Header 2 (Window Defs)
 W A    0       Writ Phrase A
 W B    4       Writ Phrase B
 V      12      Vorbis 0-12
 W A    15      Writ Phrase A
 W C    19      Writ Phrase C
 W D    23      Writ Phrase D
 V      26      Vorbis 13-26
 W E    26      Writ Phrase E
 W D    38      Writ Phrase D
 V      40      Vorbis 27-40
 W F    41      Writ Phrase F
 W D    53      Writ Phrase D (EOF)
 V      54      Vorbis 41-54
 V      69      Vorbis 55-69 (EOF)

Player begins decoding at beginning of stream. It reads the BOS pages for both codecs, then receives a non-BOS page. At this point it knows that it has two bitstreams to decode and has resolved that one is Writ and the other Vorbis. It'll continue processing the headers for both.

Next it's going to find two Writ packets (phrases A and B) and toss them into libwrit. Then it'll get to the first Vorbis data page. It now has data from both bitstreams, and it knows (from the granulepos on the Vorbis page) that it has enough data to run until 12. If there were any Writ packets before 12 they would have appeared first.

At around granule 9 the listener seeks forward to 24. This will cause a rapid seek through the file to find the first page with a granulepos greater than the seek position and begin decoding at that point.

It'll find a Vorbis packet containing 13-26 (and not use 13-23) and Writ phrase E. Again, having data from both bitstreams it can begin playing. D would normally appear at granule 24 but is not known about yet. The player knows that this is only enough to decode until 26 so, knowing enough to prebuffer, continues reading the file as it plays the media.

The next packet it finds is Writ phrase D, and passing it to libwrit, is found that the current granulepos is within the duration. It is thus displayed immediatly, as it's prebuffered, without waiting for granulepos 38. It'll keep reading (because the maximum decoded Vorbis is still 26) and find a Vorbis packet with a 40 granulepos.

As it nears 38 it'll read the file again and find Writ phrase F, which takes it out to 41. Vorbis only goes until 40, so it'll have to keep reading until the next Vorbis packet.

Next it'll find Writ phrase D, which will be ignored by libwrit because phrase D is already known (matches start granule of earlier D), and the EOF on that page marks this as the last of the Writ stream.

It'll continue reading for the next Vorbis data and find the packet for granule 54, followed by the Vorbis packet for granule 69. With that it's EOS, EOF, finished.

This is of course a simplistic example, Writ and Vorbis will rarely have granules which equal the same amount of time. Each bitstream has its' own granule -> time mapping which is calculated when muxing concurrent bitstreams within the file. So if there are 44100 Vorbis granules per second and only 4 Writ granules per second, pages would be ordered as W25 V297892 W31 V385932 W39 W41 V463057 etc. The logic used in the above example works after this granule-time mapping is calculated.

Ongoing Discussion

How does this get "encoded" and "merged"?
- <purple_haese> The muxing rule is pages are arranged in ascending order by the timestamp that is represented by their granulepos.

For what reason is the 0x00 and 0xFF byte at the beginning of header and data packet respectively?
- <xiphmont> If, after a seek, I hand your codec a header packet, what does the codec do?
- <xiphmont> It does *nothing*. If I haven't told it to reset, the header is not data, *it must ignore the header*.
- <xiphmont> this eliminates a huge raft of special cases in Ogg seeking.

"The Old Way"

The section below is for historical purposes only!

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
2003/08/17
  In a lengthy discussion with Monty and Derf the decidion to change the
  behavior of discontinuous bitstreams in Ogg, or rather, extend the
  current Ogg specification to handle discontinuous codecs, was made.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

The Ogg granulepos of each page is equal to the expiration of the text, packets are ordered by expiration time and may overlap. So, at or before text A is to be displayed, the following sequence is included:

Physical        Text    Text    Text
Location        Packet  Start   Expire  (text expire = page granulepos)
---------------------------------------
00              B       04      14
00              D       19      23
00              C       09      24
00              F       27      34
00              E       26      37
00              G       35      47
00              H       42      54
00              A       00      59
51              I       51      66

So B, D, C, F, E, G, and H are all defined before A, building a FIFO (first in first out) buffer in the player. Encoders should limit the extend of this behavior to reduce nessesary buffer size on the player side by prematurly expiring captions and recreating them periodically.

铜合金铜缓蚀剂铜金缓蚀剂铜金清洗剂铜线拉丝油 [http://www.shop263.com/i-49/6.htm 透明成核剂透明树脂涂料涂布树脂涂料催干剂涂料耐水剂涂料润滑剂涂料油漆油墨防结皮剂涂料助剂吐温脱蜡脱硫醇活化剂脱硫催化剂脱硫剂脱硫消泡剂脱硫用煤质颗粒活性炭脱膜剂脱墨剂脱漆脱漆剂脱色炭脱塑剂脱碳剂脱脂剂外墙瓷砖清洗剂烷环酸锌烷基酚烷基和芳基硅烷万能催干剂味精炭稳定剂涡轮机油肟类精细污染控制污水处理剂污水处理用铁粉无毒性钙一锌安定剂无毒亚磷酸酯无毒液体稳定剂无机氟化物无机磷酸盐无机试剂无机阻燃剂无甲醛抗水剂无水氟化钾无水六氟磷酸锂无水氯化锶无烟媒五甲基哌啶醇五水偏硅酸钠五氧化二钒戊二酸戊二酸酐戊酮雾化硅油吸附剂矽利康助剂稀释剂稀土金属萃取剂洗涤剂洗涤助剂洗和脱脂剂洗洁剂膨润土粉系磷化细结构石墨棒纤维加工助剂香蕉水香兰素橡胶橡胶促进剂橡胶防老剂橡胶分散剂橡胶流动助剂橡胶硫化橡胶硫化促进剂橡胶内脱模剂橡胶软化剂橡胶粘合剂橡皮布还原清洗剂橡塑脱模剂橡塑助剂消毒剂消光固化剂消光剂消泡剂硝基漆稀释剂硝酸硝酸铵硝酸钙硝酸盐鞋材辛醇锌铬黄锌系磷化工艺锅炉水除氧剂新型化学助剂杏壳溴化氢絮凝剂压块活性炭压缩机油压缩机转子亚磷酸亚磷酸酯亚硝酸钙盐酸颜料糊厌氧阳离子型聚丙烯酰胺阳离子荧光增白剂阳离子有机高分子絮凝剂氧化钙氧化铬绿氧化聚乙烯蜡氧化锑氧化铁红氧化铁绿氧化退浆剂氧化锌脱硫剂氧化锌预分散体氧化制合成气催化剂氧气药剂药物原料药物中间体药用活性炭药用氯化钾药用炭药用铁粉椰壳液碱液蜡液氯液态甲基四氢苯酐固化剂液体二氧化硫液体二氧化碳液体复合热稳定剂液体活性溴杀生剂液体硫转移助剂液体矽利康液体荧光增白剂液压油液状石蜡一氯蒽醌医药化工医药原料医药中间体依那普利氢化物酸酐仪器设备乙苯脱氢催化剂乙丙共聚物粘度指数改进剂乙丙橡胶乙二醇醋酸酯乙二醇二甲醚乙二醇二甲酸酯乙二醇二乙醚乙二醇甲醚乙二醇醚乙二醇双硬脂酸酯乙基乙基蒽醌乙基己酯乙烯基官能团硅烷乙酰基柠檬酸三正丁酯乙酯异丙苯异丙醚异丁醇异丁烯异氰酸正丁酯异辛酸阴极电泳涂料阴离子表面活性剂阴离子型聚丙烯酰胺銀系無機紡織整理劑印染助剂荧光颜料荧光增白剂萤石硬化剂硬脂酸硬脂酸丁酯硬脂酸钙硬脂酸酰胺硬脂酸盐硬脂酸盐热稳定剂核磁共振传递剂油剂油浆系统阻垢剂油浆阻垢剂油井水泥添加剂油墨防结皮剂油墨清油墨溶剂油漆油气层保护剂油水井环空保护液油酸油酸丁酯油酸酰胺油酸辛酯油田化学剂油田化学品油田开采助剂油田破乳剂油田污水处理剂油田助剂油温炉油性加工油油脂化工油脂活性炭有碘化物有机硅有机硅材料有机硅高效消泡剂有机硅建筑有机硅类有机硅乳液有机硅消泡剂有机磷螯合剂有机磷聚羧酸多元共聚物有机磷酸酯类阻燃剂有机膨润土有机铅稳定剂有机试剂有机烷基磷酸酯类增塑剂有机颜料有机载热体有机助剂有降粘剂有颗粒活性炭有色金属有梭织机桨料预膜剂原煤破碎炭原油破乳剂原油脱钙剂匀染剂载银炭暂时性湿强剂早强剂造纸分散剂造纸化学品造纸湿强剂造纸用糊料造纸增强剂造纸助剂增白剂增稠剂增光剂增强剂增韧剂增塑剂增塑剂油性润滑材料渣油阻垢剂粘度甲基硅油粘胶基活性炭纤维粘胶基活性炭纤维毡粘胶树脂樟脑磺酸针剂炭针剂用活性炭珍珠砂正硅酸乙酯正钛酸四丁酯支承筛板织物整理剂脂肪胺脂肪酸丁酯脂肪酸酯植物沥青植物生长调节剂纸力增强剂纸品乳液指示剂制动液制冷剂中低分子量聚异丁烯中高档润滑油中铬黄中和缓蚀剂中间体中脱剂中性酯蜡终止剂仲辛醇重氮重铬酸钾重晶石矿粉重蜡重质碳酸钙重质正构烷烃珠光剂竹醋液助催化剂助焊剂助剂助留助滤剂助滤剂助燃剂铸造用糠醇树脂专用金属切削液状碳子聚酰胺树脂紫外线吸收剂阻垢分散剂阻垢缓蚀剂阻垢剂阻聚剂阻燃剂阻油剂钻井泥浆钻井泥浆助剂铬明矾铬酸酐庚酮工程胶粘剂工业地板工业硅工业及火车用碳刷氯化钾氯化聚乙烯氯化聚乙烯无尘复合稳定润滑剂氯化石蜡氯化石蜡油氯化锶氯化锌法氯化亚砜氯化亚铁氯磺化聚乙烯烃油乳液型消泡剂通用化学试剂天然真石漆 vhttp://www.1001flower.com http://www.fm360.net http://www.touchweb.com.cn/webpage/1.htm http://www.10top.cn http://www.wxf168.com/about.htm http://www.cndevi.com http://www.swmr.net http://www.sec66.com http://www.sec66.com/index001.htm http://www.haishun.net http://www.funasia.cn http://www.yhgj.cn http://fireworks.garrywa.com/ http://global.garrywa.com/index1.htm http://www.zzhtjx.com http://www.nasbj.com/jswh2/zsgz.asp http://www.nasbj.com/guide/tzzn04.asp http://www.nasbj.com/jswh2/25400-1.htm http://www.nasbj.com http://www.nasbj.com http://www.c-flower.com http://notebook2.51.net/ http://www.7766888.com