===================================================
Zvbi - VBI decoding (teletext, closed caption, ...)
===================================================

SYNOPSIS
========

::

  import Zvbi

  cap = Zvbi.Capture("/dev/dvb/adapter0/demux0", dvb_pid=104)

  vtdec = Zvbi.ServiceDec()
  vtdec.event_handler_register(Zvbi.VBI_EVENT_TTX_PAGE, pg_handler)

  while True:
      sliced_buffer = cap.pull_sliced(2000)
      vtdec.decode(sliced_buffer)

  def pg_handler(pgtype, ev, user_data=None):
      with vtdec.fetch_vt_page(ev.pgno) as pg:
          pg.get_page_text()
          #...


DESCRIPTION
===========

This module provides a Python interface to **libzvbi**.
The ZVBI library allows accessing television broadcast data services such
as teletext or closed captions via analog or DVB video capture devices.

Official library description:
"The ZVBI library provides routines to access raw VBI sampling devices
(currently the Linux DVB & V4L2 APIs and the FreeBSD, OpenBSD,
NetBSD and BSDi bktr driver API are supported), a versatile raw VBI
bit slicer, decoders for various data services and basic search, render
and export functions for text pages. The library was written for the
Zapping TV viewer and Zapzilla Teletext browser."

The *Zvbi* Python module covers all exported libzvbi functions. Most of
the libary functions and parameters are exposed equivalently, with
adaptions to render the interface *Pythonic*.

Note: This manual page does not reproduce the full documentation provided
by libzvbi by means of doxygen: While method and parameter descriptions
are fully included, some data structures may not be not fully documented
here.  Hence when additional details are needed, it's recommended to look
at libzvbi documentation, or directly at its source code.

Class Hierarchy
===============

The following is an overview how functionality provided by *libzvbi* is
structured into classes, and how the classes are connected:

`Zvbi.Capture`_
    This class allows receiving data through a video device. For
    digital television transmissions (DVB) this mostly involves demultiplexing
    of the data service sub-stream from the overall transmission stream.
    For analog television transmission this involves capturing selected
    lines within the Vertical Blanking Interval (VBI) and "demodulating"
    the digitized wave form to raw data.
`Zvbi.CaptureRawBuf`_ and `Zvbi.CaptureSlicedBuf`_
    These are container classes, used for efficiently transferring data
    generated by the *read* and *pull* methods of the *Capture* class,
    usually to *decode* methods of classes *RawDec* or *ServiceDec*
    respectively. Alternatively one can extract data from the buffers
    for direct processing within a Python script.
`Zvbi.RawDec`_
    This class can optionally be used for manually processing raw data
    (i.e.  direct output of the analog-to-digital conversion of the video
    signal) optionally returned by the *Capture* class via *pull_raw()*
    methods et.al. For most use-cases the processing (so-called "slicing")
    done under control of the *Capture* class using *pull_sliced()* should
    be sufficient, so this class is usually not needed. This class is not
    applicable for DVB.
`Zvbi.Proxy`_
    This class allows accessing VBI devices via a proxy daemon. An
    instance of this class would be provided to the *Capture* class
    constructor.  Using the proxy instead of capturing directly from a VBI
    device allows multiple applications to capture concurrently (e.g. for
    decoding multiple data services). Not applicable to DVB, as the proxy
    does not support DVB.  (Also at least the Linux DVB driver allows
    multiple applications reading the same stream concurrently.)
`Zvbi.ServiceDec`_
    Class performing high level decoding of all supported services and
    storing the data in an internal cache. The class takes input ("sliced
    data") from the *Capture* class. The class supports callback functions
    for notifications about received data; various interfaces allow
    extracting the data in form of instances of the *Page* class, or as an
    image in PPM or XPM formats.
`Zvbi.Search`_
    This class allows searching the cache maintained by *ServiceDec* for
    pages with text matching a pattern. The search returns instances of
    class *Page*.
`Zvbi.Page`_
    Instances of this class are produced by the *ServiceDec* query
    functions or *Search*. Each instance represents a teletext (sub-)page
    or Closed Caption page. The class has various interfaces for
    extracting the text and properties of the page content.
`Zvbi.Export`_
    This class allows rendering an instance of *Page* in specific formats,
    for example as plain-text or image in various formats such as PNG or
    PPM. The result can be returned within a Python string or a *bytes*
    object respectively, or written directly to a file.

In summary: For receiving live data, you'll need at least an instance of
the *Capture* class. Your application is responsible for calling the
capture interface at 25 or 30 Hz intervals (ideally using a separate
thread that blocks on the capture function, or else using async I/O via
select/poll or polling via a timer). For standard services such as
Teletext, Closed Caption, WSS or network identification you'll need to
feed the captured data into an instance of the *ServiceDec* class, which
then drives further processing via callback notifications.  For other
services you may use the de-multiplexers listed below, or process the data
within your application directly. After that it depends on your
application which interfaces/classes you want to use for further
processing of decoded data.

Special-purpose classes for DVB:

`Zvbi.DvbDemux`_
    Class performing de-multiplexing of a transport stream received from a
    DVB driver, i.e. separating "VBI" data from a DVB PES stream (EN 301
    472, EN 301 775). Note this class is used internally by the
    *Zvbi.Capture* class for de-multiplexing. You should only use this
    class directly when the data does not originate from a local device.
`Zvbi.DvbMux`_
    This class converts sliced and optionally raw VBI data to a DVB
    Packetized Elementary Stream or Transport Stream as defined in EN 300
    472 "Digital Video Broadcasting (DVB); Specification for conveying
    ITU-R System B Teletext in DVB bit-streams" and EN 301 775 "Digital
    Video Broadcasting (DVB); Specification for the carriage of Vertical
    Blanking Information (VBI) data in DVB bit-streams".

The following classes are for de-multiplexing data services transmitted
within teletext packets. For PFC and IDL, libzvbi only supports the
protocol, but the application has to decode and store payload data. XDS is
supported by `Zvbi.ServiceDec`_ (decoding and event notifications). Most
likely none of these protocols are used anymore, as they were intended for
use via analog television broadcast:

`Zvbi.IdlDemux`_
    This class allows decoding data transmissions within a Teletext
    packet stream using *Independent Data Line* protocol (EN 300 708 section 6),
    i.e. data transmissions based on packet 8/30.
`Zvbi.PfcDemux`_
    Class for separating data transmitted in *Page Function Clear* teletext
    packets (ETS 300 708 section 4), i.e. using regular packets on a dedicated
    teletext page. Historically this protocol was used for *Nextview EPG*,
    (i.e. an Electronic Programming Guide for analog television).
`Zvbi.XdsDemux`_
    Class for separating *Extended Data Service* from a Closed Caption stream
    (EIA 608). This service allows to transmit "now & next" EPG data in
    addition to sub-titles.

.. _Zvbi.Capture:

Class Zvbi.Capture
==================

This class is used for opening a DVB or analog "VBI" device and start
receiving data from it.  The class does not support tuning of a channel.

Since parameters for capturing from DVB have little overlap with tose for
analog devices, there isn't a single constructor. Instead there are two
static methods which construct an instance. The class cannot be
instantiated directly. Nevertheless, the capture instances created by the
factory functions can be used equivalently for all other class methods.

After creating an instance, one of the *read* or *pull* methods (see below
for hints which one to use) have to be called periodically for retrieving
the data.  Usually this is done within a quasi-infinite "while" loop
(possibly in a separate thread), but most devices will support "select()"
and thus allow asynchronous I/O via event handlers. If everything else
fails, you can also use polling in fixed intervals slightly lower than the
(interlaced) video frame rate (e.g. 2*30 Hz for NTSC, 2*25 Hz for PAL)

Upon failure, the constructor and all member functions raise exception
*Zvbi.CaptureError*, containing a string describing the cause. (Additional
exception types may be used for specific error cases.)

The capture device is automatically closed when the *Zvbi.Capture* object
is destroyed.

There are two different types of capture functions: The functions named
*read* copy captured data into a bytes object (where the copying is
usually done at device driver level). In contrast the functions named
*pull* leave the data in internal buffers inside the capture context
and just return a reference to this buffer. Usually this allows the device
driver to avoid any copying, however not all devices support this (e.g.
the Linux DVB driver does not support, i.e. there is no difference in
performance between *read* and *pull*). Therefore you generally should
prefer use of the *pull* functions; only when capturing raw data for
processing by Python directly, prefer *read_raw()* as the data needs
to be copied into a permanent buffer anyway.

If you do not need "raw" data (i.e. if you do not use the `Zvbi.RawDec`_
class, you should use *pull_sliced()* or *read_sliced()* instead of
*pull()* or *read()* to avoid the overhead of returning raw data (which
has high bandwidth). DVB devices will not return raw data regardless of
the chosen interface.

**Multithreading**: The `Zvbi.Capture`_, `Zvbi.RawDec`_,
`Zvbi.ServiceDec`_ and `Zvbi.Search`_ classes are thread-safe insofar as
they allow running the capture loop (including raw decoder) and service
decoder in one thread, and further event processing or a user-interface in
another thread. The latter may interact with the capture/decoder thread
via configuration and query interfaces.
See `examples/search-ttx.py` for an example using multi-threading.


Zvbi.Capture.Dvb()
------------------

This *static* method creates and returns an instance of *Zvbi.Capture* for
DVB devices. ::

   cap = Zvbi.Capture.Dvb(dev, dvb_pid=0, trace=False)

Input parameters:

:dev:
    Path of the device to open (for Linux usually
    `/dev/dvb/adapter0/demux0`)
:dvb_pid:
    Specifies the number (PID) of a stream which contains VBI data, when
    the device is a DVB capture card. Else the parameter has no effect.
    If you omit this value, you need to configure it afterwards using
    `Zvbi.Capture.dvb_filter()`_, otherwise there will be no reception.
:trace:
    If this option is present and *True*, output of progress messages on
    `sys.stderr` is enabled.

Note the VBI PID value can often be derived from the PID for video in
`channels.conf` by adding offsets in range 3 to 30. Alternatively you can
look up the PID via Internet services such as <https://www.satindex.de/>.

Zvbi.Capture.Analog()
---------------------

This *static* method creates and returns an instance of *Zvbi.Capture* for
analog VBI devices (i.e. non-DVB devices).  The method "auto-detects" the
type of the given device by sequentially trying to access the device as
"V4l2" (i.e. analog Linux video capture device) and "bktr" (i.e.  FreeBSD
analog BSD video capture device), in this order.

::

   cap = Zvbi.Capture.Analog(dev, services, proxy=None,
                             strict=0, buffers=5, scanning=0, trace=False)

The device and service parameters are mandatory, all others are optional and
keyword-only. The parameters have the following meaning:

:dev:
    Path of the device to open (for Linux usually `/dev/vbi0`)
:services:
    Is a bit-wise OR of `VBI_SLICED_*` symbols describing the data
    services to be decoded.  See `Zvbi.RawDec.add_services()`_ for
    details.  If you want to capture raw data only, set to
    `VBI_SLICED_VBI_525`, `VBI_SLICED_VBI_625` or both.  If this parameter
    is omitted, no services will be installed (this is not supported for
    BSD "bktr" drivers).  You can do so later with
    *Zvbi.Capture.update_services()* (Note in this case the *reset*
    parameter to that function will have to be set to True.).
:proxy:
    When present, this has to be a reference to an instance of class
    `Zvbi.Proxy`_. The constructor will request start of capturing via the
    VBI proxy daemon instead of accessing the device directly. The
    following parameters are still applicable, but are passed to the
    daemon. The proxy does not support DVB devices. If the connection
    fails, the constructor will not attempt direct device access; this
    means the call shuld be repeated without the proxy parameter.
:buffers:
    Number of device buffers for raw VBI data if the driver supports
    streaming. Use higher values if you cannot guarantee there is no
    latency on reading capture data (e.g. if your GUI runs in the same
    thread). Otherwise one bounce buffer is allocated for
    *Zvbi.Capture.pull()*.
:scanning:
    Indicates the current norm: 625 for PAL and 525 for NTSC; set to 0 if
    you don't know (you should not attempt to query the device for the
    norm, as this parameter is only used for the ancient BSD "bktr" driver
    which don't support video standard query ioctls.)
:strict:
    The value can be 0, 1, or 2 for determining which services to allow
    for raw decoding. For details see `Zvbi.RawDec.add_services()`_.
:trace:
    If True, enables output of progress messages on `sys.stderr`.

Whenever possible, the proxy should be used instead of opening analog
devices directly, since it allows the user to start multiple VBI clients
concurrently. When this function fails (usually because the user hasn't
started the proxy daemon) applications should automatically fall back to
opening the device directly.

Example for using an analog source with auto-detection of a proxy: ::

    opt_device = "/dev/vbi0"
    opt_services = Zvbi.VBI_SLICED_TELETEXT_B
    opt_strict = 0
    opt_buf_count = 5
    opt_verbose = False
    try:
        proxy = Zvbi.Proxy(opt_device, appname="...", appflags=0, trace=opt_verbose)

        cap = Zvbi.Capture.Analog(opt_device, proxy=proxy,
                                  services=opt_services, strict=opt_strict,
                                  buffers=opt_buf_count, trace=opt_verbose)
    except Zvbi.ProxyError, Zvbi.CaptureError:
        # try again without proxy
        cap = Zvbi.Capture.Analog(opt_device,
                                  services=opt_services, strict=opt_strict,
                                  buffers=opt_buf_count, trace=opt_verbose)

The first call of Zvbi.Capture() in the example establishes a new
connection to a VBI proxy to open a VBI or DVB device for capturing.  On
side of the proxy daemon, the given device is opened and initialized,
equivalently as it would be done locally.  If the creation succeeds, and
any of the requested services are available, capturing is started and all
captured data is forwarded transparently to the client. See
`Zvbi.Proxy`_ for details.

The second call of Zvbi.Capture.Analog() in the example creates a local
capture context.

Zvbi.Capture.read_raw()
-----------------------

::

    raw_buffer = cap.read_raw(timeout_ms)

Read a raw VBI frame from the capture device and return it within an
object of type `Zvbi.CaptureRawBuf`_. Please refer to the descripion of
that class for details.

Parameter *timeout_ms* gives the limit for waiting for data in
milliseconds; if no data arrives within the given time, the function
raises exception *Zvbi.CaptureTimeout*.  Exception *Zvbi.CaptureError* is
raised upon error indications from the device.  Note the function may fail
if the device does not support reading data in raw format.

Note: it's generally more efficient to use *pull_raw()* instead, as
that may avoid having copying data into the new buffer allocated
for each call of *read_raw()*. See also the description of *read()* below.

Zvbi.Capture.read_sliced()
--------------------------

::

    sliced_buffer = cap.read_sliced(timeout_ms)

Captures VBI data from one video frame, "slices" the captured data samples
for VBI lines of previously configured services, and returns the sliced data
within an object of type `Zvbi.CaptureSlicedBuf`_. Please refer to the
descripion of that class for details.

Parameter *timeout_ms* gives the limit for waiting for data in
milliseconds; if no data arrives within the given time, the function
raises exception *Zvbi.CaptureTimeout*.  Exception *Zvbi.CaptureError* is
raised upon error indications from the device.

Zvbi.Capture.read()
-------------------

::

    raw_buffer, sliced_buffer = cap.read(timeout_ms)

This function is a combination of *read_raw()* and *read_sliced()*, i.e.
reads a VBI frame from the capture context and returns both the raw data
and the results of "slicing" the raw data. The results are returned in
form of a tuple which contains firstly `Zvbi.CaptureRawBuf`_ and secondly
an object of type `Zvbi.CaptureSlicedBuf`_. Please refer to the descripion
of these classes for details.

Some devices, such as DVB, may not support capturing raw VBI data. In such
a case the first element of the result tuple is set to *None*.

Parameter *timeout_ms* gives the limit for waiting for data in
milliseconds; if no data arrives within the given time, the function
raises exception *Zvbi.CaptureTimeout*.  Exception *Zvbi.CaptureError* is
raised upon error indications from the device.

**Note**: Depending on the driver, captured raw data may have to be copied
from the capture buffer into the given buffer (e.g. for V4L2 streams which
use memory-mapped buffers.)  It's generally more efficient using one of
the following *pull* interfaces. Also, unless you require raw data, it is
even more efficient using *pull_sliced()* or *read_sliced()*.

Zvbi.Capture.pull_raw()
-----------------------

::

    raw_buffer = cap.pull_raw(timeout_ms)

Read a raw VBI frame from the capture context and return it within an
object of type `Zvbi.CaptureRawBuf`_. Please refer to the descripion of
that class for details.  **Note**: The content of the returned object
remains valid only until the next call to this or any other *pull*
function. Access to an invalidated buffer will raise exception
*ValueError*

The returned *raw_buffer* can be passed to `Zvbi.RawDec.decode()`_.  If you
need to process the data by Python code, use `Zvbi.Capture.read_raw()`_
instead.

Parameter *timeout_ms* gives the limit for waiting for data in
milliseconds; if no data arrives within the given time, the function
raises exception *Zvbi.CaptureTimeout*.  Exception *Zvbi.CaptureError* is
raised upon error indications from the device.  Note the function may fail
if the device does not support reading data in raw format.


Zvbi.Capture.pull_sliced()
--------------------------

::

    sliced_buffer = cap.pull_sliced(timeout_ms)

Captures VBI data from one video frame, "slices" the captured data samples
for VBI lines of previously configured services, and returns the sliced data
within an object of type `Zvbi.CaptureSlicedBuf`_. Please refer to the
descripion of that class for details.  **Note**: The content of the
returned object remains valid only until the next call to this or any
other capture function.  Access to an invalidated buffer will raise
exception *ValueError*

Usually the returned *sliced_buffer* is passed immediately
`Zvbi.ServiceDec.decode()`_.

Parameter *timeout_ms* gives the limit for waiting for data in
milliseconds; if no data arrives within the given time, the function
raises exception *Zvbi.CaptureTimeout*.  Exception *Zvbi.CaptureError* is
raised upon error indications from the device.

Zvbi.Capture.pull()
-------------------

::

    raw_buffer, sliced_buffer = cap.pull(timeout_ms)

This function is a combination of *pull_raw()* and *pull_sliced()*, i.e.
reads a VBI frame from the capture context and returns both the raw data
and the results of "slicing" the raw data.  The results are returned in
form of a tuple which contains firstly `Zvbi.CaptureRawBuf`_ and secondly
an object of type `Zvbi.CaptureSlicedBuf`_. Please refer to the descripion
of these classes for details.

Some devices, such as DVB, may not support capturing raw VBI data. In such
a case the first element of the result tuple is set to *None*.

**Note**: The content of the returned objects remains valid only until the
next call to this or any other *pull* function. Access to an invalidated
buffer will raise exception *ValueError*

Parameter *timeout_ms* gives the limit for waiting for data in
milliseconds; if no data arrives within the given time, the function
raises exception *Zvbi.CaptureTimeout*.  Exception *Zvbi.CaptureError* is
raised upon error indications from the device.

Zvbi.Capture.parameters()
-------------------------

::

    params = cap.parameters()

Returns an instance of class `Zvbi.RawParams`_ describing the physical
parameters of the VBI source. See the description of that class for a
description of attributes.

Modifying the attributes of the returned object has no effect on the
`Zvbi.Capture`_ instance. To control raw decoding, pass the returned (and
possibly modified) parameters when instantiating class `Zvbi.RawDec`_ and
then use that class for decoding instead of the *sliced_buffer* output of
the `Zvbi.Capture`_ member functions.

**Note**: For DVB devices this function only returns dummy parameters, as
no "raw decoding" is performed in this case. In particular the sampling
format will be zero, which is an invalid value, so this can be used for
detecting this case.


Zvbi.Capture.update_services()
------------------------------

::

    services = cap.update_services(services, reset=True, commit=True, strict=0)

Not applicable to DVB:
Adds and/or removes one or more services to an already initialized capture
context.  Can be used to dynamically change the set of active services.

Internally the function will restart parameter negotiation with the
VBI device driver and then call *add_services()* on the internal raw
decoder context.  You may set *reset* to rebuild your service mask from
scratch.  Note that the number of VBI lines may change with this call
even if the function fails and raises an exception.

Result: The function returns a bit-mask of supported services among those
requested (not including previously added services), 0 upon errors.

:services:
    An integer consisting of a bit-wise OR of one or more `VBI_SLICED_*`
    constants describing the data services to be decoded.

:reset:
    When this optional parameter is set *True*, the method clears all
    previous services before adding new ones (by invoking
    `Zvbi.RawDec.reset()`_ at the appropriate time.) When *False*, new
    services are in addition to previously configured services.

:commit:
    When this optional parameter is set True, the method applies all
    previously added services to the device. Set this to *False* when
    doing multiple consecutive calls of this function; then commit should
    be set only for the last call.
    Reading data cannot continue before changes were committed (because
    capturing has to be suspended to allow resizing the VBI image.)  Note
    this flag is ignored when using the VBI proxy.

:strict:
    The meaning of this optional parameter is as described for
    `Zvbi.RawDec.add_services()`_, as that function is used internally by
    libzvbi. The parameter defaults to 0.

The function returns an integer value with bit-wise OR of `VBI_SLICED_*`
services actually decodable.

Zvbi.Capture.fd()
-----------------

::

    cap.fd()

This function returns the file descriptor used to read from the
capture context's device.  Note when using the proxy this will not
be the actual device, but a socket instead.  Some devices may also
return -1 if they don't have anything similar, or upon internal errors.

This function is equivalent to `fileno()` for Pythone file objects.

The descriptor is intended be used in a *select(2)* syscall. The
application especially must not read or write from it and must never
close the handle (instead destroy the capture context to free the
device.) In other words, the file handle is intended to allow capturing
asynchronously in the background; The handle will become readable
when new data is available.

Zvbi.Capture.get_scanning()
---------------------------

::

    scanning = cap.get_scanning()

This function is intended to allow the application to check for
asynchronous norm changes, i.e. by a different application using the
same device.  The function queries the capture device for the current
norm and returns value 625 for PAL/SECAM norms, 525 for NTSC;
0 if unknown, -1 on error.

Zvbi.Capture.flush()
--------------------

::

    cap.flush()

After a channel change this function should be used to discard all
VBI data in intermediate buffers which may still originate from the
previous TV channel. The function returns `None`.

Zvbi.Capture.get_fd_flags()
---------------------------

::

    flags = cap.get_fd_flags()

Returns properties of the capture context's device. The result is an
integer value containing a bit-wise OR of one or more of the following
constants:

VBI_FD_HAS_SELECT:
    Is set when *select(2)* can be used on the file handle returned by
    *cap.fd()* to wait for new data on the capture device file handle.

VBI_FD_HAS_MMAP:
    Is set when the capture device supports "user-space DMA".  In this case
    it's more efficient to use one of the "pull" functions to read raw data
    because otherwise the data has to be copied once more into the passed buffer.

VBI_FD_IS_DEVICE:
    Is not set when the capture device file handle is not the actual device.
    In this case it can only be used for select(2) and not for ioctl(2)

Zvbi.Capture.dvb_filter()
-------------------------

::

    cap.dvb_filter(pid)

Programs the DVB device transport stream demultiplexer to filter
out PES packets with the given *pid*. The meaning of the parameter is
equivalent to the *pid* parameter to the constructor.

Zvbi.Capture.dvb_last_pts()
---------------------------

::

    cap.dvb_last_pts()

Returns the presentation time stamp (33 bits) associated with the data
last read from the capture context. The PTS refers to the first sliced
VBI line, not the last packet containing data of that frame.

Note timestamps returned by VBI capture read functions contain
the sampling time of the data, that is the time at which the
packet containing the first sliced line arrived.

.. _Zvbi.CaptureRawBuf:

Class Zvbi.CaptureRawBuf
========================

For reasons of efficiency, captured data is not immediately converted into
Python structures. Instead class `Zvbi.Capture`_ returns an instance of this
class for raw data, which encapsulates both the data and related
attributes.

Usually this object is simply forwarded to `Zvbi.RawDec.decode()`_; in
this case there is very little overhead for managing the object by Python.
If you want to process the data directly within Python, you can access it
in the following ways:

1. Subscripting the object allows retrieving the data byte-by-byte. The
   standard *len* operator indicates the number of bytes in the buffer.
   Example: ::

    raw_buf = cap.read_raw(2000)
    for x in range(0, par.bytes_per_line):
        y = raw_buf[x]

2. In any context that expects a bytes-like object, the data content is
   accessed efficiently via direct access at C level. Example: ::

    raw_buf = cap.read_raw(2000)
    arr = bytes(raw_buf)

3. The timestamp can be retrieved via attribute *timestamp*. The value
   indicates when the data was captured in form of the number of seconds
   and fractions since 1970-01-01 00:00; the value is of type *float*.

Note the raw buffer contains all captured VBI lines consecutively in a
one-dimensional array. Length of a line can be queried from the capture
context using `Zvbi.Capture.parameters()`_: attribute *bytes_per_line*.

Note class *Zvbi.CaptureRawBuf* internally uses different memory
management depending on use of *read* or *pull* capturing methods. This
difference is not visible at the interface. **However** data retrieved by
*pull* interfaces is valid only until the next call of a capture function
on the same object.


.. _Zvbi.CaptureSlicedBuf:

Class Zvbi.CaptureSlicedBuf
===========================

For reasons of efficiency, captured data is not immediately converted into
Python structures. Instead class `Zvbi.Capture`_ returns an instance of this
class for sliced data, which encapsulates data of all sliced lines and
related attributes.

Usually this object is simply forwarded to `Zvbi.ServiceDec.decode()`_; in
this case there is very little overhead for managing the object by Python.
If you want to process the data directly within Python, you can access it
in the following ways:

1. Subscripting the object allows retrieving sliced lines one-by-one.
   The standard *len* operator indicates the number of bytes in the buffer.

2. In any context that expects an iterator, the function delivered sliced
   lines consecutively.

3. The timestamp can be retrieved via attribute *timestamp*. The value
   indicates when the data was captured in form of the number of seconds
   and fractions since 1970-01-01 00:00; the value is of type *float*.

Example:

::

    sliced_buffer = cap.pull(2000)
    for data, ident, line_no in sliced_buffer:
        ...

Iteration returns for each sliced line a named tuple of type
*Zvbi.CaptureSlicedLine*, holding the following three elements:

0. *data*: Sliced data from the respective line in the sliced buffer. The
   structure of the contained data depends on the kind of data in the VBI
   line as identified by the following attribute. (For example, for
   *VBI_SLICED_TELETEXT_B* 42 bytes are used; first two bytes contain
   Hamming-8/4 encoded magazine and packet number, which determine the
   encoding and semantics of the rest of the data.)

1. *ident*: One or more 'VBI_SLICED_*' symbols (bit-wise OR), identifying
   the type of data service. Multiple identifiers may occur e.g. for
   *VBI_SLICED_TELETEXT_B*.

2. *line_no*: Source line number according to the ITU-R line numbering
   scheme, or 0 if the exact line number is unknown. This number is
   required by the service decoder.

Note class *Zvbi.CaptureSlicedBuf* internally uses different memory
management depending on use of *read* or *pull* capturing methods. This
difference is not visible at the interface. **However** data retrieved by
*pull* interfaces is valid only until the next call of a capture function
on the same object.


.. _Zvbi.RawDec:

Class Zvbi.RawDec
=================

The functions in this section allow converting raw VBI samples (i.e. a
digitized image of the transmitted analog waveform) to payload data bytes.
This class is not applicable to DVB.

These functions are used internally by libzvbi if you use the slicer
functions of the capture object (e.g. *pull_sliced()*). This class
is useful only when capturing raw data only (e.g. *pull_raw()*),
allowing your application to take full control of slicing raw data.

After instantiating and configuring the class, the actual work is done by
`Zvbi.RawDec.decode()`_, which you'd call on the data of each captured VBI
frame.

Example control flow: ::

    cap = Zvbi.Capture("/dev/vbi0", services=VBI_SLICED_CAPTION_525)

    vtdec = Zvbi.ServiceDec()
    vtdec.event_handler_register(Zvbi.VBI_EVENT_TTX_PAGE, pg_handler)

    raw_dec = Zvbi.RawDec(cap)
    raw_dec.add_services(opt_services, opt_strict)

    while True:
        raw_buffer = cap.pull_raw(opt_timeout)

        sliced_buffer = raw_dec.decode(raw_buffer)

        vtdec.decode(sliced_buffer)


Constructor Zvbi.RawDec()
-------------------------

::

    raw_dec = Zvbi.RawDec(ref)

Creates and initializes a new raw decoder context. Parameter *ref*
specifies the physical parameters of the raw VBI image, such as the
sampling rate, number of VBI lines etc.  The parameter can be either
a reference to a capture context (`Zvbi.Capture`_)
or raw capture parameters of type `Zvbi.RawParams`_.

A properly initialized instance of *Zvbi.RawParams* can be obtained either
via method `Zvbi.Capture.parameters()`_ or `Zvbi.RawDec.parameters()`_.
In case an instance of `Zvbi.Capture`_ is used as parameter to the
constructor, decoder parameters are retrieved internally using
`Zvbi.Capture.parameters()` for convenience.

See description of class `Zvbi.RawParams`_ for a list of sampling
parameters.

Zvbi.RawDec.parameters()
------------------------

::

    services, max_rate, par = Zvbi.RawDec.parameters(services, scanning)

This is a **static** member function. The function calculates the sampling
parameters required to receive and decode the requested data services.
This function can be used to initialize hardware parameters prior to
calling `Zvbi.RawDec.add_services()`_.  The returned sampling format is fixed to
`VBI_PIXFMT_YUV420`, and attribute *bytes_per_line* is set to a reasonable
minimum.

Input parameters:

:services:
    This integer value contains a bit-wise OR of `VBI_SLICED_*` constants.
    Here (and only here) you can add `VBI_SLICED_VBI_625` or
    `VBI_SLICED_VBI_525` to include all VBI scan lines in the calculated
    sampling parameters.
:scanning:
    If *scanning* is set to 525 only NTSC services are accepted; if set to
    625 only PAL/SECAM services are accepted. When scanning is 0, the norm
    is determined from the requested services; an ambiguous set will
    result in undefined behavior.

The function returns a tuple containing the following three results:

0. An integer value containing a bit-wise OR of a sub-set of
   `VBI_SLICED_*` constants describing the data services covered by the
   calculated sampling parameters returned in *href*. This excludes services
   the libzvbi raw decoder cannot decode assuming the specified physical
   parameters.

1. Calculated maximum rate, which is to the highest data bit rate
   in **Hz** of all services requested (The sampling rate should be at least
   twice as high; attribute `sampling_rate` will be set by libzvbi to a more
   reasonable value of 27 MHz derived from ITU-R Rec. 601.)

2. An instance of class `Zvbi.RawParams`_ which contains the calculated
   sampling parameters. The content is described as for function
   `Zvbi.Capture.parameters()`_

Zvbi.RawDec.reset()
-------------------

::

    raw_dec.reset()

Resets the raw decoder context. This removes all previously added services
to be decoded (if any) but does not touch the sampling parameters. You
are free to change the sampling parameters after calling this.

Zvbi.RawDec.add_services()
--------------------------

::

    services = raw_dec.add_services(services, strict)

After you initialized the sampling parameters in raw decoder context
(according to the abilities of your VBI device), this function adds one
or more data services to be decoded. The libzvbi raw VBI decoder can
decode up to eight data services in parallel. You can call this function
while already decoding, it does not change sampling parameters and you
must not change them either after calling this.

Input parameters:

:services:
    This integer value contains a bit-wise OR of `VBI_SLICED_*` constants.
    (see also description of the *parameters* function above.)

:strict:
    The parameter can be set to 0, 1 or 2 for requesting requests loose,
    reliable or strict matching of sampling parameters respectively. For
    example if the data service requires knowledge of line numbers while
    they are not known, value 0 will accept the service (which may work if
    the scan lines are populated in a non-confusing way) but values 1 or 2
    will not. If the data service may use more lines than are sampled,
    value 1 will still accept but value 2 will not. If unsure, set to 1.

The function returns an integer value containing a bit-wise OR of
`VBI_SLICED_*` constants describing the data services that actually can be
decoded. This excludes those services not decodable given sampling
parameters of the raw decoder context.

Zvbi.RawDec.check_services()
----------------------------

::

    services = raw_dec.check_services(services, strict=0)

Check and return which of the given services can be decoded with
current physical parameters at a given strictness level.

See `Zvbi.RawDec.add_services()`_ for details on parameter semantics.

Zvbi.RawDec.remove_services()
-----------------------------

::

    services = raw_dec.remove_services(services)

Removes one or more data services given in input parameter *services*
to be decoded from the raw decoder context.  This function can be called
at any time and does not touch sampling parameters stored in the context.

Returns a set of `VBI_SLICED_*` constants describing the remaining
data services that will be decoded.

Zvbi.RawDec.resize()
--------------------

::

    raw_dec.resize(start_a, count_a, start_b, count_b)

Grows or shrinks the internal state arrays for VBI geometry changes.
Returns `None`.

Zvbi.RawDec.decode()
--------------------

::

    sliced_buffer = raw_dec.decode(raw_buffer)

This is the main service offered by the raw decoder: Decodes a raw VBI
image given in *raw_buffer*, consisting of several scan lines of raw VBI
data. The output is sorted by line number.

The input parameter *raw_buffer* can by any bytes-like object that
contains at least the number of bytes required by the capture geometry
(which is `par.bytes_per_line * (par.count_a + par.count_b)`, where *par*
is the used instance of *Zvbi.RawParams*). Usually the parameter is
an object of type `Zvbi.CaptureRawBuf`_ as returned by the *pull* kind of
`Zvbi.Capture`_ methods (e.g.  `Zvbi.Capture.pull_raw()`_).

Return value is a buffer of type `Zvbi.CaptureSlicedBuf`_, containing the
sliced output data. (Please refer to the descripion of that class for
details.) Upon errors the function raises exception *Zvbi.RawDecError*.

Usually the sliced buffer result is forwarded to `Zvbi.ServiceDec.decode()`_.
(See general description `Zvbi.RawDec`_ for an example control flow.)
Note in that case the buffer needs to be forwarded even if zero lines were
sliced; refer to description of the method for details.

Note this function attempts to learn which lines carry which data service,
or none, to speed up decoding. Hence you must use different raw decoder
contexts for different devices.


.. _Zvbi.RawParams:

Class Zvbi.RawParams
====================

This is a simple parameter container, encapsulating parameters of raw
captured data (i.e. *raw_buffer* result produced by methods
*Zvbi.Capture.read_raw()* et.al.), or for instantiating a raw decoder
of class `Zvbi.RawDec`_.

The class has the following attributes:

scanning:
    Either 525 (M/NTSC, M/PAL) or 625 (PAL, SECAM), describing the scan
    line system all line numbers refer to.

sampling_format:
    Format of the raw VBI data (one of the `VBI_PIXFMT_*` constants,
    e.g. `VBI_PIXFMT_YUV420`; see enum *vbi_pixfmt*)

sampling_rate:
    Sampling rate in Hz (i.e. the number of samples or pixels captured
    per second.)

bytes_per_line:
    Number of samples or pixels captured per scan line, in bytes. This
    determines the raw VBI image width and you want it large enough to
    cover all data transmitted in the line (with headroom).

offset:
    The distance from 0H (leading edge hsync, half amplitude point) to
    the first sample (pixel) captured, in samples (pixels). You want an
    offset small enough not to miss the start of the data transmitted.

start_a, start_b:
    First scan line to be captured in the first and second half-frame
    respectively. Numbering is according to the ITU-R line numbering
    scheme (see *vbi_sliced*). Set to zero if the exact line number isn't
    known.

count_a, count_b:
    Number of scan lines captured in the first and second half-frame
    respectively.  This can be zero if only data from one field is
    required. The sum `count_a + count_b` determines the raw VBI image
    height.

interlaced:
    In the raw vbi image, normally all lines of the second field are
    supposed to follow all lines of the first field. When this flag is
    set, the scan lines of first and second field will be interleaved in
    memory. This implies count_a and count_b are equal.

synchronous:
    Fields must be stored in temporal order, i. e. as the lines have been
    captured. It is assumed that the first field is also stored first in
    memory, however if the hardware cannot reliable distinguish fields this
    flag shall be cleared, which disables decoding of data services
    depending on the field number.



.. _Zvbi.Proxy:

Class Zvbi.Proxy
================

This class is used for receiving sliced or raw data from a VBI proxy daemon.
Using the daemon instead of capturing directly from a VBI device allows
multiple applications to capture concurrently, e.g. to decode multiple data
services.

Note the proxy is only useful if all VBI applications use it. For
applications that do not support the proxy directly, there is a library
that can overload calls to C library, so that access to the VBI device is
redirected transparently through the daemon. Details are described in the
manual *zvbi-chains(1)*. In principle it's as easy as as prepending
`zvbi-chains -dev /dev/vbi0` to the application command line.

See `examples/proxy-test.py` for examples how to use these functions.

Constructor Zvbi.Proxy
----------------------

::

    proxy = Zvbi.Proxy(dev, appname, appflags=0, trace=False)

    cap = Zvbi.Capture( ..., proxy=proxy )

Creates and returns a new proxy context, or raises exception *Zvbi.ProxyError*
upon error.  (Note in reality this call will always succeed, since a connection
to the proxy daemon isn't established until you actually open a capture context
when instantiating `Zvbi.Capture`_ with a reference to `Zvbi.Proxy`_.)

Parameters:

:dev:
    Specifies the name of the device to open, usually one of `/dev/vbi0` and up.
    The device name has to match that used by the deamon, else the daemon will
    refuse the connection, so that `Zvbi.Capture`_ calls back to direct access
    to the device.

:client_name:
    Names the client application, typically identical to ``sys.argv[0]``
    (without the path though). Can be used by the proxy daemon for fine-tuning
    scheduling, or for presenting the user with a list of currently connected
    applications.

:flags:
    Contains zero or a bit-wise OR of `VBI_PROXY_CLIENT_*` flags.

:trace:
    If True, enables output of progress messages on ``sys.stderr``.

Proxy.set_callback()
--------------------

::

    proxy.set_callback(callback=None, user_data=None)

Installs or removes a callback function for asynchronous messages (e.g.
channel change notifications.) Input parameters are a callable object
*callback* and an optional object *user_data* which is passed through to
the callback function unchanged.  Call without any arguments to remove the
callback again.

The callback function will receive the event mask (i.e. one of the
constants `VBI_PROXY_EV_*` in the following list) and, if provided,
*user_data* as parameters.

* *VBI_PROXY_EV_CHN_GRANTED*:
  The channel control token was granted, so that the client may now
  change the channel.  Note: the client should return the token after
  the channel change was completed (the channel will still remain
  reserved for the requested time.)

* *VBI_PROXY_EV_CHN_CHANGED*:
  The channel (e.g. TV tuner frequency) was changed by another proxy
  client.

* *VBI_PROXY_EV_NORM_CHANGED*:
  The TV norm was changed by another client (in a way which affects VBI,
  e.g. changes between PAL/SECAM are ignored.)  The client must update
  its services, else no data will be forwarded by the proxy until the
  norm is changed back.

* *VBI_PROXY_EV_CHN_RECLAIMED*:
  The proxy daemon requests to return the channel control token.  The
  client is no longer allowed to switch the channel and must immediately
  reply with a channel notification with flag `VBI_PROXY_CHN_TOKEN`

* *VBI_PROXY_EV_NONE*:
  No news.

Since the proxy client has no "life" on it's own (i.e.  it's not using an
internal thread or process) callbacks will only occur from inside other
proxy client or capture function calls.  The client's capture device file
descriptor will become readable when an asynchronous message has arrived
from the daemon.  Typically the application then will call read to obtain
sliced data and the callback will be invoked from inside the read
function.  Usually in this case the read call will return zero, i.e.
indicate an timeout since no actual sliced data has arrived.

Note for channel requests the callback to grant channel control may be
invoked before the request function returns.  Note you can call any
interface function from inside the callback, including the destroy
operator.

Proxy.get_driver_api()
----------------------

::

    api = proxy.get_driver_api()

This method can be used for querying which driver is behind the
device which is currently opened by the VBI proxy daemon.
Applications which only use libzvbi's capture API need not
care about this.  The information is relevant to applications
which need to switch TV channels or norms.

Returns an identifier describing which API is used on server side,
i.e. one of the symbols
`VBI_API_V4L1`,
`VBI_API_V4L2`,
`VBI_API_BKTR` or
`VBI_API_UNKNOWN` upon error.
The function will fail if the client is currently not connected to
the proxy daemon, i.e. VBI capture has to be started first.

Proxy.channel_request()
-----------------------

::

    Proxy.channel_request(chn_prio, request_chn=False, allow_suspend=FALSE,
                          sub_prio=-1, min_duration=-1, exp_duration=-1)

This method is used to request permission to switch channels or norm.
Since the VBI device can be shared with other proxy clients, clients should
wait for permission, so that the proxy daemon can fairly schedule channel
requests.

Scheduling differs at the 3 priority levels. For available priority levels
for *chn_prio* see constants `VBI_CHN_PRIO_*`.  At background level channel
changes are coordinated by introduction of a virtual token: only the
one client which holds the token is allowed to switch channels. The daemon
will wait for the token to be returned before it's granted to another
client.  This way conflicting channel changes are avoided.  At the upper
levels the latest request always wins.  To avoid interference, the
application still might wait until it gets indicated that the token
has been returned to the daemon.

The token may be granted right away or at a later time, e.g. when it has
to be reclaimed from another client first, or if there are other clients
with higher priority.  If a callback has been registered, the respective
function will be invoked when the token arrives; otherwise
*proxy.has_channel_control()* can be used to poll for it.

Input parameters:

:chn_prio:
    This mandatory parameter sets the priority. The priority should always
    be set if default *VBI_CHN_PRIO_INTERACTIVE* is not needed, to avoid
    blocking other applications.

:request_chn:
    Set this parameter to *True* if your application needs to switch
    channels.  Inversely, for only setting the *chn_prio* level to
    *VBI_CHN_PRIO_BACKGROUND* without requesting a channel, set this
    parameter to *False*.

    **Note** the following parameters have no effect when this parameter
    is set to *False*.  Inversely, when this parameter is set, the
    following parameters are mandatory.

:allow_suspend:
    Set to FALSE if your capture client needs an atomic time slice (i.e.
    would need to restart capturing from the beginning it it was
    interrupted.)

:sub_prio:
    Sub-priority for channel scheduling at "background" priority. You can
    use aribtrary values in the range 0 ... 256, but as this value is only
    meaningful in relation to priorities used by other clients, you should
    stick to the scale defined by VBI_CHN_SUBPRIO.

:min_duration:
    Minimum time slice your capture client requires. This value is used
    when multiple clients have the same sub-priority to give all clients
    channel control in a round-robin manner.

:exp_duration:
    Expected duration of use of that channel.

Zvbi.Proxy.channel_notify()
---------------------------

::

    proxy.channel_notify(notify_flags [, scanning])

Sends channel control request to proxy daemon. Parameter
*notify_flags* is an OR of one or more of the following constants:

* *VBI_PROXY_CHN_RELEASE*:
  Revoke a previous channel request and return the channel switch
  token to the daemon.

* *VBI_PROXY_CHN_TOKEN*:
  Return the channel token to the daemon without releasing the
  channel; This should always be done when the channel switch has
  been completed to allow faster scheduling in the daemon (i.e. the
  daemon can grant the token to a different client without having
  to reclaim it first.)

* *VBI_PROXY_CHN_FLUSH*:
  Indicate that the channel was changed and VBI buffer queue
  must be flushed; Should be called as fast as possible after
  the channel and/or norm was changed.  Note this affects other
  clients' capturing too, so use with care.  Other clients will
  be informed about this change by a channel change indication.

* *VBI_PROXY_CHN_NORM*:
  Indicate a norm change.  The new norm should be supplied in
  the scanning parameter in case the daemon is not able to
  determine it from the device directly.

* *VBI_PROXY_CHN_FAIL*:
  Indicate that the client failed to switch the channel because
  the device was busy. Used to notify the channel scheduler that
  the current time slice cannot be used by the client.  If the
  client isn't able to schedule periodic re-attempts it should
  also return the token.

Proxy.channel_suspend()
-----------------------

::

    proxy.channel_suspend(cmd)

Request to temporarily suspend capturing (if *cmd* is
`VBI_PROXY_SUSPEND_START`) or revoke a suspension (if *cmd*
equals `VBI_PROXY_SUSPEND_STOP`.)

Zvbi.Proxy.device_ioctl()
-------------------------

::

    proxy.device_ioctl(request, arg)

This method allows manipulating parameters of the underlying
VBI device.  Not all ioctls are allowed here.  It's mainly intended
to be used for channel enumeration and channel/norm changes.
The request codes and parameters are the same as for the actual device.
The caller has to query the driver API via *proxy.get_driver_api()*
first and use the respective ioctl codes, same as if the device would
be used directly.

Parameters and results are as documented for the **ioctl(2)** system
interface (see the respective UNIX manual page for details). Therefore
parameter *request* is the first parameter to *ioctl()* and the *arg*
byte buffer contains the data structure that the second parameter to
*ioctl* points to. Use *struct.pack* to build the argument buffer.
Example: ::

    # get current config of the selected channel
    vchan = struct.pack("=i32xiLhh", channel, 0, 0, 0, norm);
    vchan_result = proxy.device_ioctl(VIDIOCGCHAN, vchan);

After the call, the data passed in *arg* may be modified by *ioctl*
operations which return data. Therefore the the proxy returns an updated
copy of the input buffer, which is returned by the function in form of a
bytes object.

Upon failure of the I/O operation, the function raises exception *OSError*
and includes the *errno* error code and string as usual. The same
exception is also used for non-device related failures, as the proxy
response currently does not allow distinguishing them. In particular error
code *EBUSY* may indicate that the application is currently not allowed to
control the device.

Proxy.get_channel_desc()
------------------------

::

    scanning, granted = proxy.get_channel_desc()

Retrieve info sent by the proxy daemon in a channel change indication.
The function returns a tuple with two elements: scanning value (625
indicating PAL, or 525 indicating NTSC, or 0 if unknown) and a boolean
indicator if the change request was granted.

Proxy.has_channel_control()
---------------------------

Returns True if client is currently allowed to switch channels, else False.


.. _Zvbi.ServiceDec:

Class Zvbi.ServiceDec
=====================

This class is used for high level decoding of sliced data received from
an instance of the `Zvbi.Capture`_ class or the raw decoder (`Zvbi.RawDec`_).
Decoded data is stored in caches for each service. The application can
be notified via callbacks about various events. Various interfaces allow
extracting decoded data from the caches.

Constructor Zvbi.ServiceDec()
-----------------------------

::

  vt = Zvbi.ServiceDec()
  vt.event_handler_register(Zvbi.VBI_EVENT_TTX_PAGE, pg_handler)

Creates and returns a new data service decoder instance. The constructor
does not take any parameters. **However**: The type of data services to
be decoded is determined by the type of installed callbacks. Hence for
the class to do any actual decoding, you must install at least one
callback using `Zvbi.ServiceDec.event_handler_register()`_ after
construction.

Zvbi.ServiceDec.decode()
------------------------

::

  while True:
    sliced_buffer = cap.pull_sliced(2000)

    vt.decode(sliced_buffer)

This is the main service offered by the data service decoder: The method
decodes sliced VBI data from a video frame, updates the decoder state and
invokes callback functions for registered events. Note this function has
to be called for each received frame, even if it did not contain any
sliced data, because the decoder otherwise assumes a frame was lost and
may reset decoding state.

Input parameter *sliced_buffer* has to be an instance of class
`Zvbi.CaptureSlicedBuf`_ returned by *read* and *pull* methods of the
`Zvbi.Capture`_ class. The function always returns *None*. As a
side-effect, registered callbacks are invoked.

Zvbi.ServiceDec.decode_bytes()
------------------------------

::

  vt.decode_bytes(data, n_lines, timestamp)

This method is an alternate interface to *decode()*, allowing to insert
data from external sources, such as sliced data stored in a file.  Thus
the discrete method parameters replace attributes otherwise stored in
`Zvbi.CaptureSlicedBuf`_:

:data:
    Is a bytes-like object containing concatenated sliced data lines. Each
    line is a binary packed format "=LL56c", containing the service ID
    `VBI_SLICED_*`, the number of the (analog) line from where the line
    was captured, followed by 56 bytes slicer output data.

:n_lines:
    Gives the number of valid lines in the sliced data buffer. The value
    must be between 0 and len(data) / (2*4+56) (i.e. the maximum number of
    records in the given data buffer)

:timestamp:
    This should be a copy of the *timestamp* value returned by the *read*
    and *pull* capture functions within `Zvbi.CaptureSlicedBuf`_ and
    `Zvbi.CaptureRawBuf`_ class.

    The timestamps are expected to advance by 1/30 to 1/25 seconds for
    each call to this function. Different steps will be interpreted as
    dropped frames, which starts a re-synchronization cycle, eventually a
    channel switch may be assumed which resets even more decoder state. So
    this function must be called even if a frame did not contain any
    useful data (i.e. with parameter *n_lines* equal 0)

Zvbi.ServiceDec.channel_switched()
----------------------------------

::

    vt.channel_switched( [nuid] )

Call this after switching away from the channel (RF channel, video input
line, ... - i.e. after switching the network) from which this context
used to receive VBI data, to reset the decoding context accordingly.
This includes deletion of all cached Teletext and Closed Caption pages
from the cache.  Optional parameter *nuid* is currently unused by
libzvbi and defaults to zero.

The decoder attempts to detect channel switches automatically, but this
does not work reliably, especially when not receiving and decoding Teletext
or VPS (since only these usually transmit network identifiers frequently
enough.)

Note the reset is not executed until the next frame is about to be
decoded, so you may still receive "old" events after calling this. You
may also receive blank events (e. g. unknown network, unknown aspect
ratio) revoking a previously sent event, until new information becomes
available.

Zvbi.ServiceDec.classify_page()
-------------------------------

::

    (type, subno, lang) = vt.classify_page(pgno)

This function queries information about the named page. The return value
is a tuple consisting of three scalars: page number, sub-page number,
and language  Their meaning depends on the data service to which the
given page belongs:

For Closed Caption pages (*pgno* value in range 1 ... 8) *subno* will
always be zero, *language* set or an empty string. *type* will be
`VBI_SUBTITLE_PAGE` for page 1 ... 4 (Closed Caption channel 1 ... 4),
`VBI_NORMAL_PAGE` for page 5 ... 8 (Text channel 1 ... 4), or
`VBI_NO_PAGE` if no data is currently transmitted on the channel.

For Teletext pages (*pgno* in range hex 0x100 ... 0x8FF) *subno*
returns the highest sub-page number used. Note this number can be larger
(but not smaller) than the number of sub-pages actually received and
cached. Still there is no guarantee the advertised sub-pages will ever
appear or stay in cache. Special value 0 means the given page is a
"single page" without alternate sub-pages. (Hence value 1 will never
be used.) *language* currently returns the language of subtitle pages,
or an empty string if unknown or the page is not classified as
`VBI_SUBTITLE_PAGE`.

Note: The information returned by this function is volatile: When more
information becomes available, or when pages are modified (e. g. activation
of subtitles, news updates, program related pages) sub-page numbers can
increase or page types and languages can change.

Zvbi.ServiceDec.set_brightness()
--------------------------------

::

    vt.set_brightness(brightness)

Change brightness of text pages, this affects the color palette of pages
fetched with *fetch_vt_page()* and *fetch_cc_page()*.
Parameter *brightness* is in range 0 ... 255, where 0 is darkest,
255 brightest. Brightness value 128 is default.

Zvbi.ServiceDec.set_contrast()
------------------------------

::

    vt.set_contrast(contrast)

Change contrast of text pages, this affects the color palette of pages
fetched with *vt.fetch_vt_page()* and *vt.fetch_cc_page()*.
Parameter *contrast* is in range -128 to 127, where -128 is inverse,
127 maximum. Contrast value 64 is default.

Zvbi.ServiceDec.teletext_set_default_region()
---------------------------------------------

::

    vt.teletext_set_default_region(default_region)

The original Teletext specification distinguished between
eight national character sets. When more countries started
to broadcast Teletext the three bit character set id was
locally redefined and later extended to seven bits grouping
the regional variants. Since some stations still transmit
only the legacy three bit id and we don't ship regional variants
of this decoder as TV manufacturers do, this function can be used to
set a default for the extended bits. The "factory default" is 16.

Parameter *default_region* is a value between 0 ... 80, index into
the Teletext character set table according to ETS 300 706,
Section 15 (or libzvbi source file lang.c). The three last
significant bits will be replaced.

Zvbi.ServiceDec.fetch_vt_page()
-------------------------------

::

    with vt.fetch_vt_page(pgno, [subno],
                          max_level=Zvbi.VBI_WST_LEVEL_3p5,
                          display_rows=25,
                          navigation=True) as pg:
        # ... process page object 'pg'

Fetches a Teletext page designated by parameters *pgno* and optionally *subno*
from the cache, formats and returns it as an instance of `Zvbi.Page`_.  The
object can then be used to extract page content, or be passed to the
various libzvbi methods working on page objects, such as the export
functions.

The function raises exception *ServiceDecError* if the page is not cached
or could not be formatted for other reasons, for instance is a data page
not intended for display. Level 2.5/3.5 pages which could not be formatted
e. g.  due to referencing data pages not in cache are formatted at a lower
level.

Input parameters:

:page:
    Teletext page number. Not the number is hexadecimal, which means to
    retrieve text page "100", pass number 0x100. Teletext also allows
    hexadecimal page numbers (sometimes used for transmitting hidden
    data), so allowed is the full range of 0x100 to 0x8FF.

:subno:
    Defaults to `VBI_ANY_SUBNO`, which means the newest sub-page of the
    given page is returned. Else this is a sub-page number in range
    0 to 0x3F7E.

:max_level:
    Is one of the `VBI_WST_LEVEL_*` constants and specifies
    the Teletext implementation level to use for formatting.

:display_rows:
    Limits rendering to the given number of rows
    (i.e. row 0 ... *display_rows* - 1)  In practice, useful
    values are 1 (format the page header row only) or 25 (complete page).

:navigation:
    This boolean parameter can be used to skip parsing the page
    for navigation links to save formatting time.

Although safe to do, this function is not supposed to be called from
an event handler since rendering may block decoding for extended
periods of time.

**Note**: The returned object must be deleted to release resources which
are locked internally in the library during the fetch. Page objects
support Python's "Context Manager" protocol to allow doing this easily
using the "with" statement. See also the description of `Zvbi.Page`_.


Zvbi.ServiceDec.fetch_cc_page()
-------------------------------

::

    pg = vt.fetch_cc_page(pgno, reset=False)

Fetches a Closed Caption page designated by *pgno* from the cache,
formats and returns it and as an object of type `Zvbi.Page`_.
The function raises exception *ServiceDecError* upon errors.

Closed Caption pages are transmitted basically in two modes: at once
and character by character ("roll-up" mode).  Either way you get a
snapshot of the page as it should appear on screen at the present time.

With `Zvbi.ServiceDec.event_handler_register()`_ you can request a
`VBI_EVENT_CAPTION` event to be notified about pending changes (in case of
"roll-up" mode that is with each new word received) and the "dirty"
attribute provided by `Zvbi.Page.get_page_dirty_range()`_ will mark the
lines actually in need of updates, for speeding-up rendering.

If the *reset* parameter is omitted or set to *True*, the page dirty flags
in the cached paged are reset after fetching. Pass *False* only if you
plan to call this function again to update other displays.

Although safe to do, this function is not supposed to be called from an
event handler, since rendering may block decoding for extended periods of
time.

**Note**: The returned object must be deleted to release resources which
are locked internally in the library during the fetch. Page objects
support Python's "Context Manager" protocol to allow doing this easily
using the "with" statement. See the description of `Zvbi.Page`_ for an
example.

Zvbi.ServiceDec.page_title()
----------------------------

::

    title = vt.page_title(pgno, [subno])

The function makes an effort to deduce a page title to be used in
bookmarks or similar purposes for the page specified by parameters
*pgno* and *subno*.  The title is mainly derived from navigation data
on the given page.

As usual, parameter *subno* defaults to `VBI_ANY_SUBNO`, which means the
newest sub-page of the given page is used.  The function raises exception
*ServiceDecError* upon errors.

.. _Zvbi.ServiceDec event handling:

Event handling
--------------

Typically the transmission of VBI data elements like a Teletext or Closed Caption
page spans several VBI lines or even video frames. So internally the data
service decoder maintains caches accumulating data. When a page or other
object is complete it calls the respective event handler to notify the
application.

Clients can register any number of handlers needed, also different handlers
for the same event. They will be called by the `Zvbi.ServiceDec.decode()`_
function in the order in which they were registered.  Since decoding is
stopped while in the callback, the handlers should return as soon as
possible.

The handler function receives two parameters: First is the event type
(i.e. one of the `VBI_EVENT_*` constants kisted below), second a named
tuple describing the event. The type and contents of the second parameter
depends on the event type. The following event types are defined:

*VBI_EVENT_NONE*:
    No event. Second callback parameter is *None*.

*VBI_EVENT_CLOSE*:
    The vbi decoding context is about to be closed. This event is
    sent when the decoder object is destroyed and can be used to
    clean up event handlers. Second callback parameter is *None*.

*VBI_EVENT_TTX_PAGE*:
    The vbi decoder received and cached another Teletext page. For this
    type the second callback function parameter has type
    *Zvbi.EventTtx* with the following elements:

    The received page is designated by *ev.pgno* and *ev.subno*.

    *ev.roll_header* flags the page header as suitable for rolling page
    numbers, e. g. excluding pages transmitted out of order.  The
    *ev.header_update* flag is set when the header, excluding the page
    number and real time clock, changed since the last
    `VBI_EVENT_TTX_PAGE` evemt. Note this may happen at midnight when the
    date string changes. The *ev.clock_update* flag is set when the real
    time clock changed since the last `VBI_EVENT_TTX_PAGE` (that is at
    most once per second). They are both set at the first
    `VBI_EVENT_TTX_PAGE` sent and unset while the received header or clock
    field is corrupted.

    If any of the roll_header, header_update or clock_update flags
    are set, *ev.raw_header* contains the raw header data (40 bytes).
    *ev.pn_offset* will be the offset (0 ... 37) of the three-digit page
    number in the raw or formatted header. Always call
    *vt.fetch_vt_page()* for proper translation of national characters and
    character attributes; the raw header is only provided here as a means
    to quickly detect changes.

*VBI_EVENT_CAPTION*:
    A Closed Caption page has changed and needs visual update.
    For this type the second callback function parameter has type
    *Zvbi.EventCaption* with a single element *ev.pgno*, which
    indicates the "CC channel" of the received page.

    When the client is monitoring this page, the expected action is
    to call *vt.fetch_cc_page()*. To speed up rendering, more detailed
    update information can be queried via
    `Zvbi.Page.get_page_dirty_range()`_.
    (Note when the page is fetched afterward, the contents will be a
    snapshot of the status at fetch time and not event time, i.e. the
    "dirty" flags accumulate all changes since the last fetch.)

*VBI_EVENT_NETWORK*:
    Some station/network identifier has been received or is no longer
    transmitted (in the latter case all values are zero, e.g. after a
    channel switch).  The event will not repeat until a different identifier
    has been received and confirmed.  (Note: VPS/TTX and XDS will not combine
    in real life, feeding the decoder with artificial data can confuse
    the logic.)

    For this type the second callback function parameter has type
    *Zvbi.EventNetwork* with the following elements:

    0. *nuid*: Network identifier
    1. *name*: Name of the network from XDS or from a table lookup of CNIs in Teletext packet 8/30 or VPS
    2. *call*: Network call letters, from XDS (i.e. closed-caption, US only), else empty
    3. *tape_delay*: Tape delay in minutes, from XDS; 0 outside of US
    4. *cni_vps*: Network ID received from VPS, or zero if unknown
    5. *cni_8301*: Network ID received from teletext packet 8/30/1, or zero if unknown
    6. *cni_8302*: Network ID received from teletext packet 8/30/2, or zero if unknown

    Minimum times for identifying a network, when data service is
    transmitted: VPS (DE/AT/CH only): 0.08 seconds; Teletext PDC or 8/30:
    2 seconds; XDS (US only): unknown, between 0.1x to 10x seconds.

*VBI_EVENT_NETWORK_ID*:
    Like *VBI_EVENT_NETWORK*, but this event will also be sent when the
    decoder cannot determine a network name.  For this type the second
    callback function parameter has type *Zvbi.EventNetwork* with same
    contents as described above.

*VBI_EVENT_TRIGGER*:
    Triggers are sent by broadcasters to start some action on the
    user interface of modern TVs. Until libzvbi implements all of
    WebTV and SuperTeletext the information available are program
    related (or unrelated) URLs, short messages and Teletext
    page links.

    This event is sent when a trigger has fired. The second callback
    function parameter is of type *Zvbi.PageLink* and has the following
    elements:

    0. *type*: Link type: One of VBI_LINK* constants
    1. *eacem*: Link received via EACEM or ATVEF transport method
    2. *name*: Some descriptive text or empty
    3. *url*: URL
    4. *script*: A piece of ECMA script (Javascript), this may be used on
       WebTV or SuperTeletext pages to trigger some action. Usually empty.
    5. *nuid*: Network ID for linking to pages on other channels
    6. *pgno*: Teletext page number
    7. *subno*: Teletext sub-page number
    8. *expires*: The time in seconds and fractions since 1970-01-01 00:00
       when the link should no longer be offered to the user, similar to a
       HTTP cache expiration date
    9. *itv_type*: One of VBI_WEBLINK_* constants; only applicable to ATVEF triggers; else UNKNOWN
    10. *priority*: Trigger priority (0=EMERGENCY, should never be
        blocked, 1..2=HIGH, 3..5=MEDIUM, 6..9=LOW) for ordering and filtering
    11. *autoload*: Open the target without user confirmation

*VBI_EVENT_ASPECT*:
    The vbi decoder received new information (potentially from PAL WSS,
    NTSC XDS or EIA-J CPR-1204) about the program aspect ratio.

    The second callback function parameter is of type *Zvbi.AspectRatio*
    and has the following elements:

    0. *first_line*: Describe start of active video (inclusive), i.e.
       without the black bars in letterbox mode
    1. *last_line*: Describes enf of active video (inclusive)
    2. *ratio*: The picture aspect ratio in anamorphic mode, 16/9 for
       example. Normal or letterboxed video has aspect ratio 1/1
    3. *film_mode*: TRUE when the source is known to be film transferred
       to video, as opposed to interlaced video from a video camera.
    4. *open_subtitles*: Describes how subtitles are inserted into the
       picture: None, or overlay in picture, or in letterbox bars, or
       unknown.

*VBI_EVENT_PROG_INFO*:
    We have new information about the current or next program.

    The second callback function parameter is of type *Zvbi.ProgInfo*
    and has the following elements:

    0. *current_or_next*: Indicates if entry refers to the current or next program
    1. *start_month*: Month of the start date
    2. *start_day*: Day-of-month of the start date
    3. *start_hour*: Hour of the start time
    4. *start_min*: Minute of the start time
    5. *tape_delayed*: Indicates if a program is routinely tape delayed for
       Western US time zones.
    6. *length_hour*: Duration in hours
    7. *length_min*: Duration remainder in minutes
    8. *elapsed_hour*: Already elapsed duration
    9. *elapsed_min*: Already elapsed duration
    10. *elapsed_sec*: Already elapsed duration
    11. *title*: Program title text (ASCII)
    12. *type_classf*: Scheme used for program type classification:
        One of the *VBI_PROG_CLASSF* constants. Use
        `Zvbi.prog_type_string()`_ for obtaining a string from this
        value and each of the following type identifiers.
    13. *type_id_0*: Program type classifier #1 according to scheme
    14. *type_id_1*: Program type classifier #2
    15. *type_id_2*: Program type classifier #3
    16. *type_id_3*: Program type classifier #4
    17. *rating_auth*: Scheme used for rating: One of VBI_RATING_AUTH*
        constants. Use `Zvbi.rating_string()`_ for obtaining a string from
        this value and the following *rating_id*.
    18. *rating_id*: Rating classification
    19. *rating_dlsv*: Additional rating for scheme in case of
        scheme *VBI_RATING_TV_US*
    20. *audio_mode_a*: Audio mode: One of VBI_AUDIO_MODE* constants
    21. *audio_language_a*: Audio language (audio channel A)
    22. *audio_mode_b*: Audio mode (channel B)
    23. *audio_language_b*: Audio language (audio channel B)
    24. *caption_services*: Active caption pages: bits 0-7 correspond to caption pages 1-8
    25. *caption_languages*: Tuple with caption language on all 8 CC pages
    26. *aspect_ratio*: Aspect ratio description, an instance of class *Zvbi.AspectRatio*
    27. *description*: Program content description text: Up to 8 lines
        of ASCII text spearated by newline character.

**Multithreading**: The `Zvbi.Capture`_, `Zvbi.RawDec`_,
`Zvbi.ServiceDec`_ and `Zvbi.Search`_ classes are thread-safe insofar as
they allow running the capture loop (including raw decoder) and service
decoder in one thread, and further event processing or a user-interface in
another thread. The latter may interact with the capture/decoder thread
via configuration and query interfaces.

However note that callbacks registered with the service decoder will occur
within the capture thread (i.e. where you call
`Zvbi.ServiceDec.decode()`_ on captured sliced data buffers). Take care
to call only thread-safe functions of the user thread in that context.
Usually one will filter and then forward the notifications to the main
thread using some IPC mechanism (e.g. via a queued signal when using Qt).
See `examples/search-ttx.py` for an example using multi-threading.


Zvbi.ServiceDec.event_handler_register()
----------------------------------------

::

    vt.event_handler_register(event_mask, function, [user_data])

Registers a new event handler. *event_mask* can be a but-wise 'OR' of
`VBI_EVENT_*` constants. When the handler *function* with same *user_data*
is already registered, its event_mask will be changed. Any number of
handlers can be registered, also different handlers for the same event
which will be called in registration order.

The registered handler function will be invoked from within
`Zvbi.ServiceDec.decode()`_.  The function is called either with two or
three parameters, depending on the presence of parameter *user_data*
during registration:

1. Event type (i.e. one of the `VBI_EVENT_*` constants).
2. A named tuple type describing the event. The class type depends on the
   type of event indicated as first parameter.
3. A copy of the *user_data* object specified during registration. The
   parameter is omitted here when omitted during registration.

See section `Zvbi.ServiceDec event handling`_ above for a detailed
descripion of the callback parameters and information types.

Apart of adding handlers, this function also enables and disables decoding
of data services depending on the presence of at least one handler for the
respective data. A `VBI_EVENT_TTX_PAGE` handler for example enables
Teletext decoding.

This function can be safely called at any time, even from inside of a handler.
Note only 10 event callback functions can be registered in a script at the
same time.  Callbacks are automatically unregistered when the decoder object
is destroyed.

Zvbi.ServiceDec.event_handler_unregister()
------------------------------------------

::

    vt.event_handler_unregister(function, [user_data])

De-registers the event handler *handler* with optional parameter
*user_data*, if such a handler was previously registered with the same
user data parameter.

Apart from removing a handler, this function also disables decoding of
associated data services when no handler is registered to consume the
respective data. For example, removing the last handler for event type
`VBI_EVENT_TTX_PAGE` disables Teletext decoding.

This function can be safely called at any time, even from inside of a
handler removing itself or another handler, and regardless if the handler
has been successfully registered.


.. _Zvbi.Search:

Class Zvbi.Search
=================

The functions in this section allow searching across one or more
Teletext pages in the cache for a given sub-string or a regular
expression.

Constructor Zvbi.Search()
-------------------------

::

    search = Zvbi.Search(decoder=vt, pattern="",
                         page=0x100, subno=Zvbi.VBI_ANY_SUBNO,
                         casefold=False, regexp=False, direction=1,
                         progress=None, user_data=None)

Create a search context and prepare for searching the Teletext page
cache with the given sub-string or regular expression.

Input Parameters:

:decoder:
    Reference to an instance of `Zvbi.ServiceDec`_ that contains the page
    cache which is to be searched.

:pattern:
    Contains the search pattern (libzvbi expects the string in UTF-8
    encoding; the conversion from Unicode used by Python strings is done
    automatically).

:page:
    Page number of the first (forward) or last (backward) page to visit.
    Note the number is hexadecimal, which means to retrieve text page
    "100", pass number 0x100. Teletext also allows hexadecimal page
    numbers (sometimes used for transmitting hidden data), so allowed is
    the full range of 0x100 to 0x8FF.

:subno:
    Defaults to `Zvbi.VBI_ANY_SUBNO`, which means the newest sub-page of
    the given page is returned. Else this is a sub-page number in range 0
    to 0x3F7E.

:direction:
    Specifies the direction of search (from the given start page):
    1 for forward, or -1 for backward search. The search does not
    wrap-around when reaching the last or first page respectively.

:regexp:
    This boolean must be set to True when the search pattern is a regular
    expression; default is False, which means sub-string search. (Note
    libzvbi internally converts the sub-string to regular expression
    simply be escaping all special characters - so there is no performance
    gain by using sub-string search.)

:casefold:
    This boolean can be set to True to make the search case insensitive;
    default is False.

:progress:
    If present, the parameter has to be callable. The function will be
    called for each scanned page. When the function returns False, the
    search is aborted.

    The callback function receives as first parameter a reference to the
    search page (i.e. an instance of `Zvbi.Page`_), plus optionally the
    object specified as *user_data*. Note due to internal limitations only
    10 search callback functions can be registered in a script at the same
    time.  Callbacks are automatically unregistered when the search object
    is destroyed.

:user_data:
    If present, the parameter is passed through as second parameter to each
    call of the function specified by *progress*. When not specified, the
    callback is invoked with a single parameter.

**Note:** The page object is only valid while inside of the callback
function (i.e. you must not assign the object to a variable outside of the
scope of the handler function.) An exception of type *ValueError* will be
raised upon later access to an invalidated page.

**Note:**
In a multi-threaded application the data service decoder may receive
and cache new pages during a search session. When these page numbers
have been visited already the pages are not searched. At a channel
switch (and in future at any time) pages can be removed from cache.
All this has yet to be addressed.

Regular expression searching supports the standard set of operators and
constants, with these extensions:

`\\x....` or `\\X....`
    Hexadecimal number of up to 4 digits

`\\u....` or `\\U....`
    Hexadecimal number of up to 4 digits

`:title:`
    Unicode specific character class

`:gfx:`
    Teletext G1 or G3 graphic

`:drcs:`
    Teletext DRCS

`\\pN1,N2,...,Nn`
    Character properties class

`\\PN1,N2,...,Nn`
    Negated character properties class

Property definitions:

1.  alphanumeric
2.  alpha
3.  control
4.  digit
5.  graphical
6.  lowercase
7.  printable
8.  punctuation
9.  space
10. uppercase
11. hex digit
12. title
13. defined
14. wide
15. nonspacing
16. Teletext G1 or G3 graphics
17. Teletext DRCS

Character classes can contain literals, constants, and character
property classes. Example: `[abc\U10A\p1,3,4]`. Note double height
and size characters will match twice, on the upper and lower row,
and double width and size characters count as one (reducing the
line width) so one can find combinations of normal and enlarged
characters.

Zvbi.Search.__iternext__()
--------------------------

After creating an instance of *Zvbi.Search*, iteration is used to execute
the search:

::

    search = Zvbi.Search(decoder, pattern)
    for pg in search:
        # ... process pg object

As long as matching pages are found, iteration returns a reference to the
next match in form of an instance of `Zvbi.Page`_. The matching range of
text is highlighted in the page.

**Note**: The returned page object refers to temporary memory within the C
library; therefore the page content is no longer valid after continuation
of the search or start of a new search. An exception of type *ValueError*
will be raised upon access to an invalidated page.

If no matching page is found, iteration raises exception *StopIteration*
as usual. The same exception is raised when the callback returned *False*.
If iteration is continued after reaching its end, the search will restart
from the starting point given in the constructor. After cancellation
search will continue from the last visited page.

Upon other errors the function raises exception *Zvbi.SearchError*
which contains a string describing the cause, which can be because the
cache is completely empty, or internal errors.


.. _Zvbi.Page:

Class Zvbi.Page
===============

These are functions to render Teletext and Closed Caption pages directly
into memory, essentially a more direct interface to the functions of some
important export modules described in `Zvbi.Export`_.

All of the functions in this section work on page objects as returned
by the page cache's "fetch" functions (see `Zvbi.ServiceDec`_)
or the page search function (see `Zvbi.Search`_)

Page objects returned by `Zvbi.ServiceDec`_'s "fetch" interfaces must be
deleted for releasing resources which are locked internally in the library
during the fetch. `Zvbi.Page`_ supports the Python's "Context Manager"
protocol (i.e.  methods "__enter__" and "__exit__") to allow doing this
easily using the "with" statement: ::

    with vtdec.fetch_vt_page(pgno, subno) as pg:
        # process object "pg"

Any access to the page after the block defined by "with" would raise
exception *ValueError*.

Page objects returned by `Zvbi.Search`_ (or referenced as parameter to the
progress callback function) have an implicitly limited life-time as they
refer to internal static storage within the C library.  These objects are
released invalidated automatically. Any access outside of their lifetime
raises exception *ValueError*. In particular this means you must not
assign such page objects to global variables. Instead just store the page
number and fetch the page again from the cache via `Zvbi.ServiceDec`_ when
needed.


Zvbi.Page.draw_vt_page()
------------------------

::

    canvas = pg.draw_vt_page(column, row, width, height,
                             fmt=Zvbi.VBI_PIXFMT_RGBA32_LE,
                             reveal=False, flash_on=False,
                             img_pix_width, col_pix_off, row_pix_off)

Draws a complete Teletext page or a sub-section thereof into a raw image
canvas and returns it in form of a bytes object. Each teletext character
occupies 12 x 10 pixels (i.e. a character is 12 pixels wide and each line
is 10 pixels high. Note that this aspect ratio is not optimal for display,
so pixel lines should be doubled. This is done automatically by the PPM
and XPM conversion functions.)

The image is returned in form of a bytes object.  When
using format `Zvbi.VBI_PIXFMT_RGBA32_LE`, each pixel consists of 4 subsequent
bytes (RGBA). Hence the bytes array is
`4 * 12 * pg_columns * 10 * pg_rows` bytes long, where
`pg_columns` and `pg_rows` are the page width and height in
teletext characters respectively.  When using format `Zvbi.VBI_PIXFMT_PAL8`
each pixel uses one byte. In this case each pixel value is an index into
the color palette as delivered by `Zvbi.Page.get_page_color_map()`_.

Input parameters:

:column:
    Start column in the page to render at the first pixel column, defaults
    to 0.  Note this and the following three values are given as numbers
    of teletext characters (not pixels.)

:row:
    Start row in the page to render at the first pixel column, defaults to 0.

:width:
    Number of columns to render. The sum of parameters *column* plus
    *width* shall be less or equal the page width. When omitted, the
    value defaults to the page width minus the start row offset.

:height:
    Number of rows to render. The sum of parameters *row* plus
    *height* shall be less or equal the page height. When omitted, the
    value defaults to the page height minus the start column offset.

:fmt:
    Specifies the output format. Supported is `Zvbi.VBI_PIXFMT_RGBA32_LE`
    (i.e. each pixel uses 4 subsequent bytes for R,G,B,A) and
    `Zvbi.VBI_PIXFMT_PAL8` (i.e. each pixel uses one byte, which is an
    index into the color palette)

:img_pix_width:
    Is the distance between canvas pixel lines in pixels.  When omitted or
    set to 0, the image width is automatically set to the width of the
    selected region (i.e. the number of columns times 12) plus
    *col_pix_off*, if present. If specified, the value has to be equal
    or larger than the default; extraneous pixels are left zero in the
    returned image.

:col_pix_off:
    Offset to the left in pixels defining where in the canvas to draw
    the page section. By using this value combined with *img_pix_width*
    you can achieve a black border around the image.

:row_pix_off:
    Offset to the top in pixels defining where in the canvas to draw
    the page section.

:reveal:
    When omitted or set to False, characters flagged as "concealed" are
    rendered space (U+0020). When set to True the characters are rendered.

:flash_on:
    Set to True to draw characters flagged "blink" (properties) as space
    (U+0020). To implement blinking you'll have to draw the page
    repeatedly with this parameter alternating between 0 and 1.

Zvbi.Page.draw_cc_page()
------------------------

::

    canvas = pg.draw_cc_page(column, row, width, height,
                             fmt=Zvbi.VBI_PIXFMT_RGBA32_LE,
                             img_pix_width, col_pix_off, row_pix_off)

Draw a complete or sub-section of a Closed Caption page. Each character
occupies 16 x 26 pixels (i.e. a character is 16 pixels wide and each line
is 26 pixels high.)

The image is returned in a byte object.  Each
pixel uses 4 subsequent bytes (RGBA). Hence the bytes array
is `4 * 16 * pg_columns * 26 * pg_rows` bytes long, where
`pg_columns` and `pg_rows` are the page width and height in
Closed Caption characters respectively.

For details on parameters please see the previous function.

Zvbi.Page.canvas_to_ppm()
-------------------------

::

    ppm = pg.canvas_to_ppm(canvas, fmt=Zvbi.VBI_PIXFMT_RGBA32_LE,
                           aspect=True, img_pix_width=0)

This is a helper function which converts the image given in *canvas* from
a raw bytes object generated by *draw_vt_page()* or *draw_cc_page()* into
PPM format (specifically "P6" with 256 colors per dimensions, which means
there is a small ASCII header, followed by the image bitmap consisting of
3 bytes (RGB) per pixel.)

:fmt:
    The is the format of the input canvas. If must be the same value as
    passed to *draw_vt_page()* or *draw_cc_page()*.

:aspect:
    This optional boolean parameter when set to False, disables the aspect
    ratio correction (i.e. on teletext pages all lines are doubled by
    default; closed caption output ration is already correct.) Default is
    True.

:img_pix_width:
    The is the pixel width of the input canvas. It must be the same
    value as passed to *draw_vt_page()* or *draw_cc_page()*. When omitted
    or zero, the value is calculated in the same way as described for these
    methods.

Zvbi.Page.canvas_to_xpm()
-------------------------

::

    xpm = pg.canvas_to_xpm(canvas, fmt=Zvbi.VBI_PIXFMT_RGBA32_LE,
                           aspect=True, img_pix_width=0)

This is a helper function which converts the image given in *canvas* from
a raw bytes object generated by *draw_vt_page()* or *draw_cc_page()* into
XPM format. Due to the way XPM is specified, the output is an ASCII text
string (suitable for including in C source code), however returned within
a bytes object.

:fmt:
    The is the format of the input canvas. If must be the same value as
    passed to *draw_vt_page()* or *draw_cc_page()*.

:aspect:
    This optional boolean parameter when set to False, disables the aspect
    ratio correction (i.e. on teletext pages all lines are doubled by
    default; closed caption output ration is already correct.) Default is
    True.

:img_pix_width:
    The is the pixel width of the input canvas. It must be the same
    value as passed to *draw_vt_page()* or *draw_cc_page()*. When omitted
    or zero, the value is calculated in the same way as described for these
    methods.

Zvbi.Page.print_page()
----------------------

::

    txt = pg.print_page(column, row, width, height,
                        fmt='UTF-8', table=True)

Print and return the referenced Teletext or Closed Caption page
in form of a bytes object. Rows are separated by line-feed characters ("\n").
All character attributes and colors will be lost. Graphics characters,
DRCS and all characters not representable in UTF-8 will be replaced by
spaces.

:column:
    Start column in the page to render at the first output column.
    Defaults to 0.

:row:
    Start row in the page to render at the first output row.
    Defaults to 0.

:width:
    Number of columns to render. The sum of parameters *column* plus
    *width* shall be less or equal the page width (use
    *pg.get_page_size()* to determine the dimensions.) When omitted, the
    value defaults to the page width minus the start row offset.

:height:
    Number of rows to render. The sum of parameters *row* plus
    *height* shall be less or equal the page height. When omitted, the
    value defaults to the page height minus the start column offset.

:format:
    Encoding to be used in the output. Default is 'UTF-8'. Use the
    equivalent format specification when decoding the bytes into a Python
    string.

:table:
    When optional parameter *table* is set to 1, the page is scanned in
    table mode, printing all characters within the source rectangle
    including runs of spaces at the start and end of rows. This is the
    default. When set to False, sequences of spaces at the start and end
    of rows are collapsed into single spaces and blank lines are
    suppressed.


Zvbi.Page.get_page_no()
-----------------------

::

    (pgno, subno) = pg.get_page_no()

This function returns a tuple containing the page and sub-page number of
the page instance.

Teletext page numbers are hexadecimal numbers in the range 0x100 .. 0x8FF,
Closed Caption page numbers are in the range 1 .. 8.  Sub-page numbers
are used for teletext only. These are hexadecimal numbers in range
0x0001 .. 0x3F7F, i.e. the 2nd and 4th digit count from 0..F, the
1st and 3rd only from 0..3 and 0..7 respectively. A sub-page number
zero means the page has no sub-pages.

Zvbi.Page.get_page_size()
-------------------------

::

    (rows, columns) = pg.get_page_size()

This function returns a tuple containing the dimensions (i.e. row and
column count) of the page instance.

Zvbi.Page.get_page_dirty_range()
--------------------------------

::

    (y0, y1, roll) = pg.get_page_dirty_range()

To speed up rendering these variables mark the rows
which actually changed since the page has been last fetched
from cache. *y0* ... *y1* are the first to last row changed,
inclusive. *roll* indicates the
page has been vertically scrolled this number of rows,
negative numbers up (towards lower row numbers), positive
numbers down. For example -1 means row `y0 + 1 ... y1`
moved to `y0 ... y1 - 1`, erasing row *y1* to all spaces.

Practically this is only used in Closed Caption roll-up
mode, otherwise all rows are always marked dirty. Clients
are free to ignore this information.

Zvbi.Page.get_page_color_map()
------------------------------

::

    map = pg.get_page_color_map()

The function returns a tuple of length 40 which
contains the page's color palette. Each entry is a 24-bit RGB value
(i.e. three 8-bit values for red, green, blue, with red in the
lowest bits)  To convert this into the usual "`#RRGGBB`" syntax use:

::

    print("#%02X%02X%02X" %
             (rgb&0xFF, (rgb>>8)&0xFF, (rgb>>16)&0xFF))

Zvbi.Page.get_page_text_properties()
------------------------------------

::

    av = pg.get_page_text_properties()

The function returns tuple which contains the properties of all characters
on the given page, starting with those of the first row left to right,
directly followed by the next row etc. (use *pg.get_page_size()* for
unpacking). Each entry is a bit-field. The members are (in
ascending order, width in bits given behind the colon):

* foreground color:8:
  Index into the color map returned by `Zvbi.Page.get_page_color_map()`_
* background color:8:
  Index into the color map returned by `Zvbi.Page.get_page_color_map()`_
* opacity:4:
  Character opacity, as one of constants:

  + `VBI_TRANSPARENT_SPACE` (replace char with video),
  + `VBI_TRANSPARENT_FULL` (replace background with video),
  + `VBI_SEMI_TRANSPARENT` (mix video into background), or
  + `VBI_OPAQUE` (no transparency).

  Both *foreground* and *background* colors are valid
  independent of this flag.
* size:4:
  One of the constants:

  + `VBI_NORMAL_SIZE`,
  + `VBI_DOUBLE_WIDTH`,
  + `VBI_DOUBLE_HEIGHT`,
  + `VBI_DOUBLE_SIZE`,
  + `VBI_OVER_TOP`
    (i.e. this is to the right of `VBI_DOUBLE_WIDTH` or `VBI_DOUBLE_SIZE`),
  + `VBI_OVER_BOTTOM`
    (i.e. this is below `VBI_OVER_TOP`, thus lower right of `VBI_DOUBLE_SIZE`),
  + `VBI_DOUBLE_HEIGHT2`
    (i.e. this is lower half of a `VBI_DOUBLE_HEIGHT` character in the row above), or
  + `VBI_DOUBLE_SIZE2`
    (i.e. this is lower half of a `VBI_DOUBLE_SIZE` character in the row above).

  Note characters marked `VBI_DOUBLE_HEIGHT2`, `VBI_DOUBLE_SIZE2`,
  `VBI_OVER_TOP`, `VBI_OVER_BOTTOM` have the same character unicode and
  attributes as the top/left anchor. Partial characters (like a single
  `VBI_DOUBLE_HEIGHT2`) will not appear, so characters with these
  attributes can be safely ignored when scanning the page content.
* underline:1:
  Boolean *True* for underlined, else *False*.
* bold:1:
  Boolean *True* for bold, else *False*.
* italic:1:
  Boolean *True* for displaying the character slanted right, else *False*.
* flash:1:
  Boolean *True* for characters that should flash (i.e. blink), else
  *False*. Note the GUI is responsible for rendering the page periodically
  with such characters present, or omitted. See
  `Zvbi.Page.draw_vt_page()`_.
* conceal:1:
  Boolean *True* for characters that should be concealed (i.e. replaced by
  space character), else *False*.
  See also option *reveal* for `Zvbi.Page.draw_vt_page()`_.
* proportional:1:
  Currently always *False*, i.e. use fixed-width fonts for rendering.
* link:1:
  Boolean *True* if the character is part of a hyperlink, else *False*.
  Call `Zvbi.Page.resolve_link()`_ to get more information.

Zvbi.Page.get_page_text()
-------------------------

::

    txt = pg.get_page_text( replace_chr='' )

The function returns the complete page text in form of a string (i.e.
Unicode).  This function is very similar to *pg.print_page()*,
but does not insert or remove any characters so that it's guaranteed
that characters in the returned string correlate exactly with the
array returned by `Zvbi.Page.get_page_text_properties()`_.

The optional parameter can be set to a single-character string for
replacing "private-use" Unicode code points in range [0xE000, 0xF8FF] with
that character.  Note these code points are used for representing
graphical characters. When not replacing them, there will be errors when
passing the string to transcoder functions (such as Pythons's *decode()*.)

Zvbi.Page.resolve_link()
----------------------------

::

    href = pg.resolve_link(column, row)

The page instance *pg* (in practice only Teletext pages) may contain
hyperlinks such as HTTP URLs, e-mail addresses or links to other
pages. Characters being part of a hyperlink have their "link" flag
set in the character properties (see
`Zvbi.Page.get_page_text_properties()`_),
this function returns a dict with a more verbose description of the link.

The function returns an object of type *Zvbi.PageLink*. See chapter
`Event handling`_, item *VBI_EVENT_TRIGGER* for a description of the
contents.

Zvbi.Page.resolve_home()
----------------------------

::

    href = pg.resolve_home()

All Teletext pages have a built-in home link, by default
page 100, but can also be the magazine intro page or another
page selected by the editor.

The function returns an object of type *Zvbi.PageLink*. See chapter
`Event handling`_, item *VBI_EVENT_TRIGGER* for a description of the
contents.


.. _Zvbi.Export:

Class Zvbi.Export
=================

Once libzvbi received, decoded and formatted a Teletext or Closed Caption
page you will want to render it on screen, print it as text or store it
in various formats.  libzvbi provides export modules converting a page
object into the desired format or rendering directly into an image.

Currently the following export formats are supported:

* Text
* HTML
* PNG (image with lossless compression)
* PPM (image without compression)
* XPM (image without compression)

All the formats support boolean option "reveal"; all the image formats
support boolean option "aspect". The meaning of the options is the same as
for `Zvbi.Page.draw_vt_page()`_.

Constructor Zvbi.Export()
-------------------------

::

    exp = Zvbi.Export(keyword)

Creates a new object for exporting a `Zvbi.Page`_ object in
the format implied by parameter *keyword*. As a special service you can
initialize options by appending to the *keyword* parameter like this:
`keyword = "keyword; quality=75.5, comment=\"example text\"";`

Note: A quick overview of all export formats and options can be
obtained by running the demo script `examples/explist.py` in the
ZVBI package.

Zvbi.Export.info_enum()
-----------------------

::

    href = Zvbi.Export.info_enum(index)

This is a **static** member function.
The function enumerates all available export modules. You should start
with *index* 0, incrementing until the function raises exception
*StopIteration*.
Some modules may depend on machine features or the presence of certain
libraries, thus the list can vary from session to session.

The function returns a dict with the following elements:

* "keyword"
* "label"
* "tooltip"
* "mime_type"
* "extension"

Zvbi.Export.info_keyword(keyword)
---------------------------------

::

    href = Zvbi.Export.info_keyword(keyword)

This is a **static** member function.
Similar to the above function *info_enum()*, this function returns info
about available modules, although this one searches for an export module
which matches the given *keyword*. If no match is found the function
raises exception *Zvbi.ExportError*, else a dict as described above.

Zvbi.Export.info_export()
-------------------------

::

    href = exp.info_export()

Returns the export module info for the export instance in form of a dict.
The contents are as described for the previous two functions.

Zvbi.Export.option_info_enum()
------------------------------

::

    href = exp.option_info_enum(index)

This member function enumerates the options available for the given
export instance.
You should start at *index* 0, incrementing until the function
raises exception *StopIteration*.  On success, the function returns a
dict with the following elements:

* "type"
* "keyword"
* "label"
* "min"
* "max"
* "step"
* "def"
* "menu"
* "tooltip"

The content format of min, max, step and def depends on the type,
i.e. it may be an integer, double or string.

If present, the value of "menu" is a tuple.  Elements in the tuple are of
the same type as min, max, etc.  If no label or tooltip are available for
the option, these elements are undefined.

Zvbi.Export.option_info_keyword()
---------------------------------

::

    href = exp.option_info_keyword(keyword)

Similar to the above function *exp.option_info_enum()* this
function returns info about available options, although this one
identifies options based on the given *keyword*.

Zvbi.Export.option_set()
------------------------

::

    exp.option_set(keyword, opt)

Sets the value of the option named by *keword* to *opt*.
Raises exception *Zvbi.ExportError* on failure.  Example: ::

    exp.option_set('quality', 75.5);

Note the expected type of the option value depends on the keyword.
The ZVBI interface module automatically converts the option into
type expected by the libzvbi library.

Mind that options of type `VBI_OPTION_MENU` must be set by menu
entry number (integer), all other options by value. If necessary
it will be replaced by the closest value possible. Use function
*exp.option_menu_set()* to set options with menu by menu entry.

Zvbi.Export.option_get()
------------------------

::

    opt = exp.option_get(keyword)

This function queries and returns the current value of the option
named by *keyword*.

Zvbi.Export.option_menu_set()
-----------------------------

::

    exp.option_menu_set(keyword, entry)

Similar to *exp.option_set()* this function sets the value of
the option named by *keyword* to *entry*, however it does so
by number of the corresponding menu entry. Naturally this must
be an option with menu.

Zvbi.Export.option_menu_get()
-----------------------------

::

    entry = exp.option_menu_get(keyword)

Similar to *exp.option_get()* this function queries the current
value of the option named by *keyword*, but returns this value as
number of the corresponding menu entry. Naturally this must be an
option with menu.

Zvbi.Export.to_stdio()
----------------------

::

    exp.to_stdio(pg, fd)

This function writes contents of the `Zvbi.Page`_ instance given in *pg*,
converted to the respective export module format, to a stream created from
*fd* using fdopen(3). This means *fd* has to be a value as returned by
*fileno()* on a file-like object.

The function raises exception *Zvbi.ExportError* upon errors.
Note this function may write incomplete files when an error occurs.

You can call this function as many times as you want, it does not
change state of the export or page objects.

Zvbi.Export.to_file()
---------------------

::

    exp.to_file(pg, file_name)

This function writes contents of the `Zvbi.Page`_ instance given in *pg*,
converted to the respective export module format, into a new file specified
by *file_name*. When an error occurs the file will be deleted.
The function raises exception *Zvbi.ExportError* upon errors.

You can call this function as many times as you want, it does not
change state of the export or page objects.

Zvbi.Export.to_memory()
-----------------------

::

    data = exp.to_memory(pg)

This function writes contents of the `Zvbi.Page`_ instance given in *pg*,
converted to the respective export module format, into a bytes object.

The function raises exception *Zvbi.ExportError* upon errors.


.. _Zvbi.DvbMux:

Class Zvbi.DvbMux
=================

These functions convert raw and/or sliced VBI data to a DVB Packetized
Elementary Stream or Transport Stream as defined in EN 300 472 "Digital
Video Broadcasting (DVB); Specification for conveying ITU-R System B
Teletext in DVB bit-streams" and EN 301 775 "Digital Video Broadcasting
(DVB); Specification for the carriage of Vertical Blanking Information
(VBI) data in DVB bit-streams".

Note EN 300 468 "Digital Video Broadcasting (DVB); Specification for
Service Information (SI) in DVB systems" defines another method to
transmit VPS data in DVB streams. Libzvbi does not provide functions
to generate SI tables but the *encode_dvb_pdc_descriptor()* function
is available to convert a VPS PIL to a PDC descriptor (since version 0.3.0)

Constructor Zvbi.DvbMux()
-------------------------

::

    mx = Zvbi.DvbMux( {pes=True | ts_pid=pid}
                      [,callback [,user_data]]
                      [,raw_par] )

There are two separate semantics:

* When option *pes* is present and *True*, a DVB VBI multiplexer instance is
  created for converting raw and/or sliced VBI data to MPEG-2 Packetized
  Elementary Stream (PES) packets as defined in the standards EN 300 472 and
  EN 301 775.

* When option *ts_pid* is present and non-zero, a DVB VBI multiplexer
  instance is created for converting raw and/or sliced VBI data to MPEG-2
  Transport Stream (TS) packets as defined in the standards EN 300 472 and
  EN 301 775.

The following keyword-only parameters are available:

:pes:
    When this option is set, a PES stream will be encoded.
    This option must not be combined with option *ts_pid*.

:ts_pid:
    When this option is present and non-zero, a TS stream will be encoded.
    The PID value is a program identifier that will be stored in the
    header of generated TS packets. The value must be in range 0x0010 to
    0x1FFE inclusive. This option must not be combined with option *pes*.

:callback:
    Specifies a handler function which is called by method *feed()* when a
    new TS or PES packet is available. When the callback parameter is
    omitted, packets have to be extracted via iteration. See method
    *feed()* for additional details.

:user_data:
    The given object is passed through transparently as extra parameter to
    the specified *callback* when invoked from within the *feed()* method.

:raw_par:
    This optional parameter of type `Zvbi.RawParams`_ describes attributes
    of raw data optionally provided to method `Zvbi.DvbMux.feed()`_. The
    parameters have to match the capture source (i.e. usually one would
    obtain them via `Zvbi.Capture.parameters()`_ called on your capture
    instance). The parameter need not be specified when no raw data is to
    be encoded.

Wen raw decoder parameters are provided, they have to meet the following
constraints:

* videostd_set must contain one or more bits from the
  `VBI_VIDEOSTD_SET_625_50`.
* scanning must be 625 (libzvbi 0.2.x only)
* sampling_format must be `VBI_PIXFMT_Y8` or `VBI_PIXFMT_YUV420`.
  Chrominance samples are ignored.
* sampling_rate must be 13500000.
* offset must be >= 132.
* bytes_per_line must be >= 1.
* offset + bytes_per_line must be <= 132 + 720.
* synchronous must be *True*.


Zvbi.DvbMux.feed()
------------------

This method provides the main service of class *Zvbi.DvbMux*: ::

    mx.feed(service_mask, sliced_buffer, raw_buf=None, pts=0)

This function converts raw and/or sliced VBI data to one DVB VBI PES
packet or one or more TS packets as defined in EN 300 472 and EN 301 775.

**Usage with a callback function:**

When the DVB multiplexer was intiantiated with a callback function
parameter, the *feed()* function invokes the callback for each generated
PES or TS packet before it returns. Example for use of the callback: ::

    # callback function, invoked out of DvbMux.feed()
    def feed_cb(pkg, outfile):
        bwritten = outfile.write(pkg)
        return (bwritten == len(pkg))

    outfile = open(SOME_FILE, "wb")
    mx = Zvbi.DvbMux(pes=True, callback=feed_cb, user_data=outfile)

    sliced_buffer = cap.pull_sliced(1000)
    mx.feed(service_mask, sliced_buffer)

The packet parameter is a *Bytes* object containing a copy of the
generated packet. Parameter *user_data* loops back the object passed to
the constructor; it is omitted here if not present in the constructor
parameters.  The handler function has to return *True* on success and
*False* on failure. In case of the latter, the *feed()* function
terminates with exception *Zvbi.DvbMuxError*.

**Usage without a callback function:**

When the DVB multiplexer was intiantiated without a callback function
parameter, generated packets have to be retrieved using iteration on the
*DvbMux* object. Example usage for this mode: ::

    outfile = open(SOME_FILE, "wb")
    mx = Zvbi.DvbMux(pes=True)

    sliced_buffer = cap.pull_sliced(1000)
    mx.feed(service_mask, sliced_buffer)

    for pes_pkg in mx:
        outfile.write(pes_pkg)

Note each iteration pre-allocates a packet buffer of size
`Zvbi.DvbMux.get_max_pes_packet_size()`_, which defaults to theoretical
maximum 65504. For compatibility with decoders compliant to the Teletext
buffer model defined in EN 300 472 the maximum should not exceed 1472
bytes. For this reason and for efficiency, is is recommended to limit the
maximum to a value such as 2048 using `Zvbi.DvbMux.set_pes_packet_size()`_.

Input parameters:

:service_mask:
    Only data services in this set will be encoded. Other data services in
    the sliced buffer will be discarded without further checks. Create a
    set by ORing `VBI_SLICED_*` constants. Only the following data
    services can be encoded:

    1. `VBI_SLICED_TELETEXT_B` on lines 7 to 22 and 320 to 335
       inclusive, or with line number 0 (undefined). All Teletext
       lines will be encoded with data_unit_id 0x02 ("EBU Teletext
       non-subtitle data").
    2. `VBI_SLICED_VPS` on line 16.
    3. `VBI_SLICED_CAPTION_625` on line 22.
    4. `VBI_SLICED_WSS_625` on line 23.

:sliced_buffer:
    This mandatory parameter of type `Zvbi.CaptureSlicedBuf`_ contains the
    sliced VBI data to be converted. All data must belong to the same
    video frame.

:raw_buf:
    This optional parameter may pass an object of type
    `Zvbi.CaptureRawBuf`_ that contains raw VBI data to be converted.  The
    object shall contain sample data of size (*rdp.count_a* +
    *rdp.count_b*) lines times *rdp.bytes_per_line* (where *rdp* is the
    raw decoder parameter set passed during instantiation).  The function
    encodes only those lines which have been selected by sliced lines in
    the *sliced_buffer* object with id `VBI_SLICED_VBI_625` The data field of
    these structures is ignored. When the sliced input buffer does not
    contain such structures, *raw_buf* can be omitted.

    Raw VBI data with id `VBI_SLICED_VBI_625` can be encoded on lines 7 to
    23 and 320 to 336 inclusive. Note for compliance with the Teletext
    buffer model defined in EN 300 472, EN 301 775 recommends to encode at
    most one raw and one sliced, or two raw VBI lines per frame.

:pts:
    This Presentation Time Stamp will be encoded into the PES packet. Bits
    33 ... 63 are discarded. Resolution is 90 kHz. Note the value can be
    derived from the timestamp in *sliced_buffer* as
    `sliced_buffer.timestamp * 90000.0`.

The function may raise exception *Zvbi.DvbMuxError* upon failures, which
may occur under the following circumstances:

* The maximum PES packet size, or the value selected with
  `Zvbi.DvbMux.set_pes_packet_size()`_, is too small to contain all
  the sliced and raw VBI data.
* The sliced array is not sorted by ascending line number,
  except for elements with line number 0 (undefined).
* An unsupported service was requested for encoding of sliced data.
* A selected raw data line is not in the allowed ranges listed above.
* A sliced line within *sliced_buffer* contains a physical line number
  outside the valid range specified above.
* Parameter *raw_dec* was not specified during instantiation although
  the *sliced_buffer* contains a structure with id `VBI_SLICED_VBI_625`.
* One or more members of the raw decoder parameters are invalid.
* A sliced line within *sliced_buffer* with id `VBI_SLICED_VBI_625`
  contains a physical line number outside the ranges defined by *raw_dec*
  parameters.


Zvbi.DvbMux.mux_reset()
-----------------------

::

    mx.mux_reset()

This function clears the internal buffers of the DVB VBI multiplexer.

After a reset call the *feed()* function will encode a new PES packet,
discarding any data of the previous packet which has not been consumed by
the application.

Zvbi.DvbMux.get_data_identifier()
---------------------------------

::

    id = mx.get_data_identifier()

Returns the data_identifier the multiplexer encodes into PES packets.

Zvbi.DvbMux.set_data_identifier()
---------------------------------

::

    mx.set_data_identifier(data_identifier)

This function can be used to specify the *data_identifier* byte
to be stored in PES packets.

For compatibility with decoders compliant to EN 300 472 this should be a
value in the range 0x10 to 0x1F inclusive. The values 0x99 to 0x9B
inclusive as defined in EN 301 775 are also permitted.  The default
data_identifier is 0x10.

The method raises exception *Zvbi.DvbMuxError* if the given identifier is
outside the valid range.

Zvbi.DvbMux.get_min_pes_packet_size()
-------------------------------------

::

    size = mx.get_min_pes_packet_size()

Returns the minimum size of PES packets the multiplexer generates.

Zvbi.DvbMux.get_max_pes_packet_size()
-------------------------------------

::

    size = mx.get_max_pes_packet_size()

Returns the maximum size of PES packets the multiplexer generates.

Zvbi.DvbMux.set_pes_packet_size()
---------------------------------

::

    mx.set_pes_packet_size(min_size, max_size)

Determines the minimum and maximum total size of PES packets generated by
the multiplexer, including all header bytes. When the data to be stored in
a packet is smaller than the minimum size, the multiplexer will fill the
packet up with stuffing bytes. When the data is larger than the maximum
size the *feed()* function will fail.

The PES packet size must be a multiple of 184 bytes, in the range 184
to 65504 bytes inclusive, and this function will round *min_size* up
and *max_size* down accordingly. If after rounding the maximum size is
lower than the minimum, it will be set to the same value as the
minimum size.

The default minimum size is 184, the default maximum 65504 bytes. For
compatibility with decoders compliant to the Teletext buffer model
defined in EN 300 472 the maximum should not exceed 1472 bytes.

The method raises exception *Zvbi.DvbMuxError* upon failure (out of
memory).

Zvbi.DvbMux.dvb_multiplex_sliced()
----------------------------------

This **static method** converts the sliced VBI data in the *sliced* buffer to
VBI data units as defined in EN 300 472 and EN 301 775 and stores them in
*packet* as output buffer.  Thus this function provides a fraction of the
functionality of the *feed()* method.

::

    packet_left, sliced_left =
        Zvbi.DvbMux.dvb_multiplex_sliced(packet, packet_left,
                                         sliced, sliced_left,
                                         service_mask,
                                         data_identifier=0x10, stuffing= False)

Input parameters:

:packet:
    This parameter has to be a *bytearray* that is to be filled with the
    generated packet. The size of the *bytearray* needs to be
    pre-initialized to the initial value of *packet_left*.

:packet_left:
    Contains the number of bytes available in the *packet* object. It will
    be decremented by the cumulative size of the successfully stored data
    units.

:sliced:
    This has to be an object of type `Zvbi.CaptureSlicedBuf`_. It contains
    the sliced VBI data to be converted.

:sliced_left:
    Indicates initially the number of sliced lines in the *sliced* buffer,
    or it can be zero.

:service_mask:
    Only data services in this set will be encoded. Other data services in
    the *sliced* buffer will be discarded without further checks. Create a
    set by bit-wise ORing *VBI_SLICED_* values.  The parameter defauls to
    the set of all allowed services, which are:

    * VBI_SLICED_TELETEXT_B on lines 7 to 22 and 320 to 335 inclusive
    * VBI_SLICED_VPS on line 16
    * VBI_SLICED_CAPTION_625 on line 22
    * VBI_SLICED_WSS_625 on line 23

:data_identifier:
    When the given value lies in range 0x10 to 0x1F inclusive, the encoded
    data units will be padded to data_unit_length 0x2C for compatibility
    with EN 300 472 compliant decoders. The *data_identifier* itself will
    **not** be stored in the output buffer.

:stuffing:
    If this optional parameter is specified and set *True*, and space
    remains in the output buffer after all data has been successfully
    converted, or *sliced_left* is zero, the function fills the buffer up
    with stuffing data units.

The function returns a tuple of two values:

0. Returns the value of parameter *packet_left*, decremented by
   the cumulative size of the successfully stored data units.
1. Returns the value of parameter *sliced_left* decremented by the number
   of successfully converted VBI lines in *sliced*

The method raises exception *Zvbi.DvbMuxError* upon failure. The method
may fail for the following causes:

* *packet_left* is less than 2 (the minimum data unit size is two bytes).
  The output buffer remains unchanged in this case.
* The *data_identifier* is in range 0x10 to 0x1F inclusive and
  *packet_left* is not a multiple of 46. The output buffer remains
  unchanged in this case.
* The lines in the *sliced* buffer are not sorted by ascending line
  number, except for elements with line number 0 (undefined).
* The service mask contains a serive type that is not one of the allowed
  types listed above.
* A sliced line selected by *service_mask* contains a line number outside
  the valid range specified above.

All errors are recoverable. Just call the function again, possibly after
skipping the offending sliced line (by reducing the value of
*sliced_left*), to continue where it left off. Note *packet_left* must be
at least 2 (or a multiple of 46) in each call.

Simplified example without error checking: ::

    sliced_buffer = cap.pull_sliced(1000)

    pkg = bytearray(2024) # multiple of 46
    pkg_left = len(pkg)
    sliced_left = len(sliced_buffer)
    pkg_left, sliced_left = \
        Zvbi.DvbMux.multiplex_sliced(pkg, pkg_left, sliced_buffer, sliced_left)
    del pkg[pkg_left :]

**Note:**
According to EN 301 775 all lines stored in one PES packet must belong to
the same video frame (but the data of one frame may be transmitted in
several successive PES packets). They must be encoded in the same order as
they would be transmitted in the VBI, no line more than once. Samples may
have to be split into multiple segments and they must be contiguously
encoded into adjacent data units. The function cannot enforce this if
multiple calls are necessary to encode all samples.

Zvbi.DvbMux.dvb_multiplex_raw()
-------------------------------

This **static method**  converts one line of raw VBI samples in *raw* to one or
more "monochrome 4:2:2 samples" data units as defined in EN 301 775, and stores
them in the *buf* output buffer. Thus this function provides a fraction of the
functionality of the feed() method.

::

    packet_left, raw_left =
        Zvbi.DvbMux.dvb_multiplex_raw(packet, packet_left,
                                      raw, raw_left,
                                      data_identifier, videostd_set, line,
                                      first_pixel_position, n_pixels_total,
                                      stuffing=False)

Input parameters:

:data_identifier:
    When the given value lies in range 0x10 to 0x1F inclusive, the encoded
    data units will be padded to data_unit_length 0x2C for compatibility
    with EN 300 472 compliant decoders. The *data_identifier* itself will
    **not** be stored in the output buffer.

:videostd_set:
   The *line* parameter will be interpreted according to this set of video
   standards. It must not change until all samples have been encoded. Only
   one of two values are permitted: *Zvbi.VBI_VIDEOSTD_SET_625_50* or
   *Zvbi.VBI_VIDEOSTD_SET_525_60*.

:line:
    The ITU-R line number to be encoded in the data units.
    It must not change until all samples have been encoded.

:first_pixel_position:
    The horizontal offset where decoders shall insert the first sample in
    the VBI, counting samples from the start of the digital active line as
    defined in ITU-R BT.601.  Usually this value is zero and
    *n_pixels_total* is 720.  *first_pixel_position* + *n_pixels_total*
    must not be greater than 720. This parameter must not change until all
    samples have been encoded.

:n_pixels_total:
    Total size of the raw input buffer in bytes, and the total number of
    samples to be encoded. Initially this value must be equal to
    *raw_left*, and it must not change until all samples have been
    encoded.

:stuffing:
    If this optional parameter is specified and set *True*, and space
    remains in the output buffer after all data has been successfully
    converted, or *sliced_left* is zero, the function fills the buffer up
    with stuffing data units.

The function returns a tuple of two values:

0. Returns the value of parameter *packet_left*, decremented by
   the cumulative size of the successfully stored data units.
1. Returns the value of parameter *raw_left* decremented by the number of
   successfully converted samples.

The method raises exception *Zvbi.DvbMuxError* upon failure. The method
may fail for the following causes:

* *packet_left* is less than two (the minimum data unit size is two bytes).
* *raw_left* is zero.
* The *data_identifier* is in range 0x10 to 0x1F inclusive and
  *packet_left* is not a multiple of 46.
* The *videostd_set* is ambiguous.
* The *line* parameter is outside the valid range, that is 7 to
  23 and 270 to 286 for 525 line standards, 7 to 23 and 320 to 336
  for 625 line standards. All numbers inclusive.
* *raw_left* is greater than *n_pixels_total*
* *first_pixel_position* + *n_pixels_total* is greater than 720.

The output buffer remains unchanged on all errors.

.. _Zvbi.DvbDemux:

Class Zvbi.DvbDemux
===================

This class extracts sliced VBI data from a DVB Packetized Elementary
Stream (PES) or Transport Stream (TS) as defined in EN 300 472 "Digital
Video Broadcasting (DVB); Specification for conveying ITU-R System B
Teletext in DVB bitstreams" and EN 301 775 "Digital Video Broadcasting
(DVB); Specification for the carriage of Vertical Blanking Information
(VBI) data in DVB bitstreams".

Constructor Zvbi.DvbDemux
-------------------------

::

    dvb = Zvbi.DvbDemux( [callback [, user_data]] [,max_sliced=64] )

Creates and returns a new DVB VBI demultiplexer context taking a PES
stream as input.

The constructor takes the following optional keyword-only parameters:

:callback:
    When this parameter is present, it must be a function object. The
    function will be called from inside of method *feed* whenever a
    complete sliced data of a VBI frame is available during
    de-multiplexing the provided stream data.

    When the callback parameter is omitted, VBI data has to be extracted
    via iteration.  See *dvb.feed()* for additional details.

:user_data:
    If present, the passed object is appended to the callback's parameter
    list. IF omitted, one parameter less is passed to the callback.

:max_sliced:
    This optional parameter indicates the size of the buffer to allocate
    for the sliced buffer to be returned by iteration (i.e. when no
    callback is defined). The default is 64 lines per frame.

Zvbi.DvbDemux.feed()
--------------------

::

    dvb.feed(buf)

This function takes an arbitrary number of DVB PES data bytes in *buf*,
filters out *PRIVATE_STREAM_1* packets, filters out valid VBI data units,
and stores them in objects of type `Zvbi.CaptureSlicedBuf`_ function may
raise exception *Zvbi.DvbDemuxError* if the data contained errors. When a
callback is configured, the exception is also raised if the callback
function returned value *False*.

Note the timestamp included in the generated `Zvbi.CaptureSlicedBuf`_
instantes is derived from the presentation timestamp (PTS) of the DVB
stream, converted from 1/90000 Hz to a second resolution (as *Float* type
to allow fractions). The value does not represent seconds since
1970-Jan-01, but can nevertheless be used equivalently to timestampts
generated by class `Zvbi.Capture`_.

Note: Demultiplexing of raw VBI data is not supported;
any raw data present in the stream will be discarded.

**Usage with a callback function:**

When the de-multiplexer was intiantiated with a callback function
parameter, the *feed* function invokes the callback for each completed VBI
frame before it returns. The callback is invoked with the following
signature: ::

    ok = callback(sliced_buffer, user_data)

The handler function has to return *True* on success and *False* on failure.
Parameters to the callback have the following meaning:

* *sliced_buffer* is an object of type `Zvbi.CaptureSlicedBuf`_,
  containing the sliced data and attributes (i.e. this is the same
  type as returned by `Zvbi.Capture`_ methods). The *timestamp* attribute
  is derived from the PTS value in the stream, converted from 90 kHz to
  one second (with fraction) resolution.

  **Note**: The sliced buffer instance passed here is valid only for the
  duration of the callback execution. (When assigned to a global variable
  and accessed after the callback returns, exception *ValueError* will be
  raised.)

* *user_data* loops back the object passed via *user_data* parameter
  to the constructor. If not specified there, this parameter is omitted
  here.

**Usage without a callback function:**

When the de-multiplexer was intiantiated without a callback function
parameter, the *feed()* function only stores a reference to the given
input buffer. Actual de-multiplexing is done when the object is used as an
iterator.  The iteration has to be completed before feeding new data, else
exception *ZvbiDvbDemuxError* is raised.

Each iteration returns an object of type `Zvbi.CaptureSlicedBuf`_,
containing the sliced data and attributes (i.e.  this is the same type as
returned by `Zvbi.Capture`_ methods). The *timestamp* attribute is derived
from the PTS value in the stream, converted from 90 kHz to one second
(with fraction) resolution.

Example usage for this mode: ::

    dvb.feed(buf)
    for sliced_buffer in dvb:
        # process sliced_buffer...

See also `examples/dvb-mux.py` for a working example.

At most the maximum number of sliced lines indicated via parameter
*max_sliced* (or default value 64) to the constructor is returned. If the
frame contains more lines, they are discarded sliently. To detect this,
you can set *max_sliced* to plus one of the expected maximum and treat
reaching this value as overflow error. (The number of sliced lines in the
returned buffer can be queried via `len(sliced_buffer)`.)

Note in contrary to callback mode, the life-time of returned
*sliced_buffer* objects is not limited by the library, as a separate
buffer, owned by the instance, is allocated for each iteration.

Zvbi.DvbDemux.set_log_fn()
--------------------------

::

    dvb.set_log_fn(mask, log_fn=None, user_data=None)

The DVB demultiplexer supports the logging of errors in the PES stream and
information useful to debug the demultiplexer.
With this function you can redirect log messages generated by this module
from general log function `Zvbi.set_log_fn()`_ to a
different function or enable logging only in the DVB demultiplexer.

The callback can be removed by calling the function with a zero mask value
or without a handler parameter.

Input parameters:

:mask:
    An integer value specifying which kind of information to log.
    If zero, logging is disabled (and parameter *log_fn* is ignored).
    Else this is a bit-wise OR of one or more of the constants
    `VBI_LOG_ERROR`,
    `VBI_LOG_WARNING`,
    `VBI_LOG_NOTICE`,
    `VBI_LOG_INFO`,
    `VBI_LOG_DEBUG`,
    `VBI_LOG_DRIVER`,
    `VBI_LOG_DEBUG2`,
    `VBI_LOG_DEBUG3`.
:log_fn:
    If present, has to be a callable object that is invoked for each
    message with the parameters listed below. If omitted, logging is
    disabled.
:user_data:
    If present, this object is passed through to the handler function as
    last parameter.

The handler function is called with the following parameters: *level*,
*context*, *message* and, if given, *user_data*. Meaning of the parameters
is the same as described for `Zvbi.set_log_fn()`_.

Note: Kind and contents of log messages may change in the future.


Zvbi.DvbDemux.reset()
---------------------

::

    dvb.reset()

Resets the DVB demux to the initial state as after creation.
Intended to be used after channel changes.

.. _Zvbi.IdlDemux:

Class Zvbi.IdlDemux
===================

The functions in this section decode data transmissions in Teletext
**Independent Data Line** packets (EN 300 708 section 6), i.e. data
transmissions based on teletext packet 8/30.

The decoder only supports format A.

Constructor Zvbi.IdlDemux()
---------------------------

::

    idl = Zvbi.IdlDemux(channel, address, callback, [user_data] )

Creates and returns a new Independent Data Line format A
(EN 300 708 section 6.5) demultiplexer.

Input parameters:

:channel:
    Process packets of this channel.
:address:
    Process packets with this service data address.
:callback:
    Parameters *callback* and optional *user_data* specify a handler and
    passed-through parameter which is called when a new packet is available.
    Passing the callback is mandatory as the data is otherwise discarded.
:user_data:
    This optional parameter is passed through to the callback function,
    if specified. Else the *user_data* parameter to the callback is
    omitted.

The callback function is invoked with the following parameters for each
received data packet:

0. *buffer*: A bytes object containing the data received in the packet
   (i.e. payload data after stripping teletext packet header)
1. *flags*: A bit-wise OR of *VBI_IDL_DATA_* constants.
2. Optionally the *user_data* object specified as constructor parameter;
   if the parameter was specified to the constructor, it is omitted here.


Zvbi.IdlDemux.feed()
--------------------

::

    idl.feed(buf)

This function takes 42 bytes of a Teletext packet, detects packets
belonging to the configured data channel and address and calls the
callback function given during context creation when new payload data is
available.

Parameter *buf* is a scalar containing a teletext packet's data
(at least 42 bytes, i. e. without clock run-in and framing code),
as returned by the slicer functions.

The function returns *None*. Exception *Zvbi.IdlDemuxError* is raised if
the buffer contained incorrectible errors.

Zvbi.IdlDemux.feed_frame()
--------------------------

This function works like *idl.feed()* but takes a complete sliced buffer
(i.e. a full frame's worth of sliced data as returned by
`Zvbi.Capture.pull_sliced()`_) and automatically filters out all unrelated
teletext packets.  This can be used to "short-circuit" the capture output
with the demultiplexer. Example: ::

    sliced_buffer = cap.pull_sliced(1000)
    idl.feed_frame(sliced_buffer)

The callback function given during context creation is called when new
payload data is available.  The function returns *None*.  Exception
*Zvbi.IdlDemuxError* is raised if any of the teletext packets in the buffer
contained incorrectible errors.

.. _Zvbi.PfcDemux:

Zvbi.IdlDemux.reset()
---------------------

::

    idl.reset(dx)

Resets the IDL demux context, useful for example after a channel change.

Class Zvbi.PfcDemux
===================

Separating data transmitted in Page Function Clear Teletext packets
(ETS 300 708 section 4), i.e. using regular packets on a dedicated
teletext page.

Constructor Zvbi.PfcDemux()
---------------------------

::

    pfc = Zvbi.PfcDemux(pgno, stream, callback, [user_data] )

Creates and returns a new demultiplexer context.

Input parameters:

:page:
    Number of the teletext page on which the data is transmitted.
    (Usually data is transmitted on a "non-decimal looking" page
    number such as `1DF`.)
:stream:
    Number of the stream to be de-multiplexed.
:callback:
    Parameters *callback* and optional *user_data* specify a handler and
    passed-through parameter which is called when a new packet is available.
    Passing the callback is mandatory as the data is otherwise discarded.
:user_data:
    This optional parameter is passed through to the callback function,
    if specified. Else the *user_data* parameter to the callback is
    omitted.

The callback function is invoked with the following parameters for each
correctly assembled data block.

0. *page*: Teletext page number given in constructor.
1. *stream*: Stream identifier given in constructor.
2. *application_id*: Application ID received in the AI block.
3. *block*: A bytes object containing the data received in the block.
4. Optionally the *user_data* object specified as constructor parameter;
   if the parameter was specified to the constructor, it is omitted here.

Note multiple small blocks may fit within a teletext packet; inversely
larger blocks may span multiple teletext packets. Therefore the callback
may be called 0, 1, or more times per received teletext packet.

Zvbi.PfcDemux.feed()
--------------------

::

    pfc.feed(buf)

This function takes a raw stream of Teletext packets, detects if they
belong to the requested page and stream and assembles the data transmitted
in this packet in an internal buffer. When a data block is complete it
calls the handler given during creation.

Zvbi.PfcDemux.feed_frame()
--------------------------

This function works like *pfc.feed()* but takes a complete sliced buffer
(i.e. a full frame's worth of sliced data as returned by
`Zvbi.Capture.pull_sliced()`_) and automatically filters out all unrelated
teletext packets.  This can be used to "short-circuit" the capture output
with the demultiplexer. Example: ::

    sliced_buffer = cap.pull_sliced(1000)
    pfc.feed_frame(sliced_buffer)

The callback function given during context creation is called when a new
data block is complete.  The function returns *None*.  Exception
*Zvbi.PfcDemuxError* is raised if any of the teletext packets in the buffer
contained incorrectible errors.

Zvbi.PfcDemux.reset()
---------------------

::

    pfc.reset()

Resets the PFC demux context, useful for example after a channel change.


.. _Zvbi.XdsDemux:

Class Zvbi.XdsDemux
===================

Separating "Extended Data Service" (XDS) from a Closed Caption stream (EIA
608).

Constructor Zvbi.XdsDemux()
---------------------------

::

    xds = Zvbi.XdsDemux(callback, user_data)

Creates and returns a new Extended Data Service (EIA 608) demultiplexer.

Parameters *callback* and optionally *user_data* specify a handler and
passed-through parameter which is called when a new packet is available.
Passing the callback is mandatory as the data is otherwise discarded.

The callback function is invoked with the following parameters:

0. *xds_class* is the XDS packet class, i.e. one of the `VBI_XDS_CLASS_*`
   constants.
1. *xds_subclass* holds the subclass; meaning depends on the main class.
2. *buffer* is a bytes object holding the packet data (already parity decoded.)
3. Optionally *user_data*, if specified as constructor parameter; else the
   parameter is omitted.

Zvbi.XdsDemux.feed()
--------------------

::

    xds.feed(buf)

This function takes two successive bytes of a raw Closed Caption stream,
filters out XDS data and calls the handler function given during context
creation when a new packet is complete.

Parameter *buf* is a bytes-like object holding data from NTSC line 284 (as
returned by the slicer functions.)  Only the first two bytes in the buffer
are used.

The function returns *None*. Exception *Zvbi.XdsDemuxError* is raised if
the buffer contained parity errors.

Zvbi.XdsDemux.feed_frame()
--------------------------

This function works like *xds.feed()* but takes a complete sliced buffer
(i.e. a full frame's worth of sliced data as returned by
`Zvbi.Capture.pull_sliced()`_) and automatically filters out all
non-closed caption lines.  This can be used to "short-circuit" the capture
output with the demultiplexer. Example: ::

    sliced_buffer = cap.pull_sliced(1000)
    xds.feed_frame(sliced_buffer)

The callback function given during context creation is called when a new
packet is complete.  The function returns *None*.  Exception
*Zvbi.XdsDemuxError* is raised if any of the CC lines in the buffer
contained parity errors.

Zvbi.XdsDemux.reset()
---------------------

::

    xds.reset()

Resets the XDS demux context, useful for example after a channel change.


Miscellaneous (Zvbi)
====================

Zvbi.lib_version()
------------------

::

    major, minor, micro = Zvbi.lib_version()

Returns the major, minor and micro versions of the ZVBI library in
form of a tuple.

Zvbi.check_lib_version()
------------------------

::

    Zvbi.check_lib_version(major, minor, micro)

Returns True if the library version is at least the given version.
The last two parameters are optional and default to zero. Example: ::

    if not Zvbi.check_lib_version(0, 2, 35):
        print("Library version is outdated")


Zvbi.set_log_fn()
-----------------

::

    Zvbi.set_log_fn(mask, log_fn=None, user_data=None)

Various functions within the *libzvbi* library can print warnings, errors
and information useful for debugging the library or application. By
default such messages are disabled. This function allows enabling these
messages by specifying a function for printing them. (Note: The kind and
contents of messages logged by particular functions may change in the
future.)

Input parameters:

:mask:
    An integer value specifying which kind of information to log.
    If zero, logging is disabled (and parameter *log_fn* is ignored).
    Else this is a bit-wise OR of one or more of the constants
    `VBI_LOG_ERROR`,
    `VBI_LOG_WARNING`,
    `VBI_LOG_NOTICE`,
    `VBI_LOG_INFO`,
    `VBI_LOG_DEBUG`,
    `VBI_LOG_DRIVER`,
    `VBI_LOG_DEBUG2`,
    `VBI_LOG_DEBUG3`.

:log_fn:
    Callable object to be called for log messages. Omit this parameter to
    disable logging.

:user_data:
    If present, the parameter is passed through as last parameter to each
    call of the function specified by *log_fn*. When not specified, the
    callback is invoked with one less parameter.

The handler function is called with the following parameters:

1. *level*: Is an integer with the value of one of the `VBI_LOG_*`
   constants enumerated above.
2. *context*: Is a text string describing the module where the event
   occurred.
3. *message*: String with the actual message text.
4. *user_data*: The object passed as *user_data* parameter to *set_log_fn()*.
   The parameter is omitted from the call when omitted as parameter to
   *set_log_fn()*.

Note if you simply want to have the messages printed to *sys.stderr*, you
can use `Zvbi.set_log_on_stderr()`_ instead. Also note you can register
only one log handler; further registrations will override the previous
one.

Zvbi.set_log_on_stderr()
------------------------

::

    Zvbi.set_log_on_stderr(mask)

This function enables error logging just like `Zvbi.set_log_fn()`_,
but uses the library's internal log function which prints
all messages to *stderr*, i.e. on the terminal.

*mask* is a bit-wise OR of zero or more of the `VBI_LOG_*`
constants. The mask specifies which kind of information to log.
To disable logging, pass a zero mask value.

Zvbi.par8()
-----------

::

    par_val = par8(val)

This function encodes the given 7-bit value with Parity. The
result is an 8-bit value in the range 0..255.
Exception *ValueError* is raised when the input is out of range.

Zvbi.unpar8()
-------------

::

    val = Zvbi.unpar8(par_val)

This function decodes the given Parity encoded 8-bit value. The result
is a 7-bit value in the range 0...127 or a negative value when a
parity error is detected.  (Note: to decode parity while ignoring
errors, simply mask out the highest bit, i.e. val &= 0x7F)
Exception *ValueError* is raised when the input is out of range.

Zvbi.par_str()
--------------

::

    byte_str = Zvbi.par_str(data)

This function encodes a string in an Unicode or bytes-like object with
parity and returns the result within a bytes object.

Zvbi.unpar_str()
----------------

::

    byte_str = Zvbi.unpar_str(data)

This function decodes a Parity encoded string and returns the result
within a bytes object. (Note despite the name the characters cannot
by returned as Python Unicode string, as the encoding is not known.)

Zvbi.rev8()
-----------

::

    val = Zvbi.rev8(val)

This function reverses the order of all bits of the given 8-bit integer
value and returns the result. This conversion is required for decoding
certain teletext elements which are transmitted MSB first instead of the
usual LSB first (the teletext VBI slicer already inverts the bit order so
that LSB are in bit #0)

Zvbi.rev16()
------------

::

    val = Zvbi.rev16(val)

This function reverses the order of all bits of the given 16-bit integer
value and returns the result.

Zvbi.rev16p()
-------------

::

    val = Zvbi.rev16p(data, offset=0)

This function reverses all bits of two consecutive bytes in the given
bytes-like object starting at the given offset and returns them as a
16-bit integer value.

Zvbi.ham8()
-----------

::

    ham_val = Zvbi.ham8(val)

This function encodes the given 4-bit integer value (i.e. range 0..15)
with Hamming-8/4.  The result is an 8-bit value in the range 0..255.

Zvbi.unham8()
-------------

::

    val = Zvbi.unham8(ham_val)

This function decodes the given Hamming-8/4 encoded integer value. The
result is a 4-bit value, or -1 upon incorrectable errors.

Zvbi.unham16p()
---------------

::

    val = Zvbi.unham16p(data, offset=0)

This function decodes two Hamming-8/4 encoded bytes (taken from the
bytes-like object *data* at the given *offset*). The result is an 8-bit
integer value, or -1 upon incorrectable errors.

Zvbi.unham24p()
---------------

::

    val = Zvbi.unham24p(data, offset=0)

This function decodes three Hamming-24/18 encoded bytes (taken from the
bytes-like object *data* at the given *offset*). The result is a 12-bit
integer value, or -1 upon incorrectable errors.

Zvbi.dec2bcd()
--------------

::

    bcd = Zvbi.dec2bcd(dec)

Converts an integer value (i.e. a regular two's complement encoded binary
value) in range 0 ... 999 into a packed BCD number (binary coded decimal)
in range  0x000 ... 0x999, where each hex nibble is in range 0..9.
Exception *ValueError* is raised when the input is out of range.

Zvbi.bcd2dec()
--------------

::

    dec = Zvbi.bcd2dec(bcd)

Converts a packed BCD number in range 0x000 ... 0xFFF into a regular
integer value (i.e. two's complement binary) in range 0 ... 999.
Exception *ValueError* is raised when the input is out of range or
invalid BCD.

Zvbi.add_bcd()
--------------

::

    bcd_sum = Zvbi.add_bcd(bcd1, bcd2)

Adds two packed BCD numbers, returning a packed BCD sum. Arguments
and result are in range 0xF0000000 ... 0x09999999, that
is -10**7 ... +10**7 - 1 in decimal notation. To subtract you can
add the 10's complement, e. g. -1 = 0xF9999999.

The return value is a packed BCD number.  Exception *ValueError* is raised
when the input values are out of range or invalid BCD.

Zvbi.is_bcd()
-------------

::

    yes_no = Zvbi.is_bcd(bcd)

Tests if *bcd* forms a valid BCD number. The argument must be
in range 0x00000000 ... 0x09999999. Return value is 0 if *bcd*
contains hex digits 0xA ... 0xF.

Zvbi.decode_vps_cni()
-------------------------

::

    cni = Zvbi.decode_vps_cni(data)

This function takes a sliced VPS line in form of a bytes-like object
holding at least 13 bytes. The function decodes the network identifier and
returns it as a 16-bit CNI value. The function raises exception
*ZvbiError* in case of errors.

Zvbi.encode_vps_cni()
-------------------------

::

    byte_str = Zvbi.encode_vps_cni(cni)

This function receives a 16-bit CNI value and returns a VPS line,
or raises exception *ZvbiError* in case of an invalid CNI value that
cannot be encoded (e.g. out of range)

Zvbi.rating_string()
--------------------

::

    rating = Zvbi.rating_string(auth, id)

Translate a program rating code given by *auth* and *id* into a
string, native language.  Raises exception *Zvbi.Error* if this
code is undefined. The input parameters will usually originate from
elements *ev.rating_auth* and *ev.rating_id*, provided within an instance
of type *Zvbi.ProgInfo* for an event of type `VBI_EVENT_PROG_INFO` raised
by `Zvbi.ServiceDec event handling`_.

Zvbi.prog_type_string()
-----------------------

::

    prog_type = Zvbi.prog_type_string(classf, id)

Translate a *vbi_program_info* program type code into string, currently
English only. Raises exception *Zvbi.Error* if this code is undefined.

The input parameters will usually originate from elements *ev.type_classf*
and *ev.type_id_0* et.al., provided within an instance of type
*Zvbi.ProgInfo* for an event of type `VBI_EVENT_PROG_INFO` raised by
`Zvbi.ServiceDec event handling`_.

Zvbi.iconv_caption()
--------------------

::

    str = Zvbi.iconv_caption(src, repl_char=None)

Converts a string of EIA 608 Closed Caption characters into a Unicode
string.  The function ignores parity bits and the bytes 0x00 ... 0x1F,
except for two-byte special and extended characters (e.g. music note 0x11
0x37)  See also *caption_unicode()*.

The optional second parameter *repl_char* specifies an UCS-2 replacement
for characters that are not representable with standard Unicode code
points.  The parameter is expected in form of a string containing a single
character. When omitted, the function will raise exception *Zvbi.Error* if
the source buffer contains unrepresentable characters.

Returns the converted string as an Unicode object. The function raises
exception *Zvbi.Error* when the source buffer contains non-representable
code points, or when the conversion fails, or when it runs out of memory.

Zvbi.caption_unicode()
----------------------

::

    str = Zvbi.caption_unicode(c, to_upper=False)

Converts a single Closed Caption character code into a Unicode string.
Codes in range 0x1130 to 0x1B3F are special and extended characters
(e.g. caption command 11 37).

Input character codes in *c* are in ranges:

* 0x0020 ... 0x007F
* 0x1130 ... 0x113F
* 0x1930 ... 0x193F
* 0x1220 ... 0x123F
* 0x1A20 ... 0x1A3F
* 0x1320 ... 0x133F
* 0x1B20 ... 0x1B3F

When True is passed as optional second parameter, the character is converted
into upper case. (Often programs are captioned in all upper case, but
except for one character the basic and special CC character sets contain
only lower case accented characters.)


Examples
========

The `examples` sub-directory in the *Zvbi* package contains a number of
scripts used to test the various interface functions. You can also use
them as examples for your code.

**Note**: Example command lines for scripts capturing directly from a
DVB/VBI device shown below do not include options required for configuring
the device. Generally, you'll need either
`--device /dev/dvb/adapter0/demux0 --pid PID` for DVB, or
`--device /dev/vbi0` for analog capture devices.
The VBI PID value can often be derived from the PID for video in
`channels.conf` by adding offsets in range 3 to 30. Alternatively you can
look up the PID via Internet services such as <https://www.satindex.de/>.

:capture.py:
    Example for the use of class `Zvbi.Capture`_.
    The script captures VBI data from a device and slices it. The result
    can be dumped for the various data services in form of hex-string plus
    roughly decoded text (where applicable) for inspection of incoming
    data. Altnernatively, output can be written to STDOUT in binary format
    for further processing (decoding) by piping the data into one of the
    following example scripts.  Call with option `--help` for a list
    of options.
    (This is a translation of `test/capture.c` in the libzvbi package.)

:decode.py:
    Example for the use of class `Zvbi.ServiceDec`_.
    Decodes sliced VBI data on STDIN, e.g. ::

      ./capture.py --sliced | ./decode.py --ttx

    Call with option `--help` for a list of options.
    (This is a direct translation of `test/decode.c` in the libzvbi package.)

:caption.py:
    Example for the use of class `Zvbi.ServiceDec`_, type
    *Zvbi.VBI_EVENT_CAPTION*.  When called without an input stream, the
    application opens a GUI displaying a demo messages sequente (character
    sets etc.) for debugging the decoder. For displaying live CC streams
    you can use the following: ::

      ./capture.py --sliced | ./caption.py

    The buttons on top of the GUI switch between Closed Caption channels
    1-4 and Text channels 1-4.
    (This is a translation of `test/caption.c` in the libzvbi package,
    albeit based on TkInter here.)

:export.py:
    Example for the use of export actions in class `Zvbi.Export`_. The
    script captures from a device until the specified Teletext page (range
    100-8FF) or Closed Caption page (range 1-8) is found and then exports
    the page content in the requested format. The format is specified as
    first parameter and the page number as second parameter on the command
    line. Alternatively, the script can be used to continuously export a
    single or all received pages. Examples: ::

      ./export.py text 100       # teletext page 100 as text
      ./export.py text all       # continuously all teletext pages
      ./export.py --loop text 1  # continuously closed caption
      ./export.py "png;reveal=1" 100 > page_100.png

    Use ./explist.py for listing supported export formats (aka "modules")
    and possible options. Note options are appended to the module name,
    separated by semicolon as shown in the second example.
    (This is a translation of `test/export.c` in the libzvbi package, plus
    support for Closed Caption)

:explist.py:
    Example for the use of export option management in class `Zvbi.Export`_.
    Test of page export options and menu interfaces.  The script lists
    all available export modules (i.e. formats) and options.
    (This is a direct translation of `test/explist.c` in the libzvbi package.)

:hamm.py:
    Automated test of the odd parity and Hamming encoder and decoder functions.
    Note this test runs for a long time.
    (This is a direct translation of `test/hamm.c` in the libzvbi package.)

:network.py:
    Example for the use of class `Zvbi.ServiceDec`_, type *Zvbi.VBI_EVENT_NETWORK*.
    This script shows how to identify a network from data transmitted in
    XDS packets, Teletext packet 8/30 format 1 and 2, and VPS packets.
    The script captures directly from a device until the currently tuned
    channel is identified by means of VPS, PDC et.al.
    (This is a direct translation of `examples/network.c` in the libzvbi package.)

:proxy-test.py:
    Example for the use of class `Zvbi.Proxy`_.
    The script can capture either from a proxy daemon or a local device and
    dumps captured data on the terminal. Also allows changing services and
    channels during capturing (e.g. by entering "+ttx" or "-ttx" on stdin.)
    Start with option `-help` for a list of supported command line options.
    (This is a direct translation of `test/proxy-test.c` in the libzvbi package.)

:test-vps.py:
    This script contains tests for encoding and decoding the VPS data service on
    randomly generated data.
    (This is a direct translation of `test/test-vps.c` in the libzvbi package.)

:search-ttx.py:
    Example for the use of class `Zvbi.Search`_ and for multi-threading.
    The script captures and caches teletext pages in a separate thread.
    The main thread displays the progress of captured pages until the
    RETURN key is pressed, then prompts for a search string.  A search
    across cached teletext pages is started, and the content of matching
    pages is printed on the terminal.

:browse-ttx.py:
    Example for the use of classes `Zvbi.Page`_ and `Zvbi.Export`_ for
    rendering teletext pages. The script captures teletext from a given
    device and renders selected teletext pages in a simple GUI using
    TkInter.

:osc.py:
    Example for the use of class `Zvbi.RawDec`_.
    The script continuously captures raw VBI data and displays the data as
    an animated gray-scale image. Below this, the analog wave line of one
    selected video line is plotted (i.e. essentially simulating an
    oscilloscope). For the selected line, the resulting data from slicing
    is also shown if decoding is successful.
    (This script is loosely based on `test/osc.c` in the libzvbi package.)

:dvb-mux.py:
    Example for the use of class `Zvbi.DvbMux`_.
    This script excercises the DVB multiplexer functions: The script first
    opens a capture device (normally this will be an analog device, as the
    goal is forwarding VBI services from analog to digital domain), then
    continuously captures VBI data, encodes it in a DVB packet stream and
    wites the result to STDOUT. The output stream can be decoded
    equivalently to that of capture.py, which is:

        ./dvb-mux.py | ./decode.py --pes --all

:dvb-demux.py:
    Example for the use of class `Zvbi.DvbDemux`_.  This script excercises
    the DVB de-multiplexer functions: The script directly opens a DVB
    capture device, and reads the incoming packets. The de-multiplexer is
    used to extract VBI packets, which are then forwarded to STDOUT.  The
    output stream can be decoded equivalently to that of capture.py, which
    is: ::

      ./dvb-demux.py --sliced | ./decode.py --ttx

    **Note**: Instead of reading from the device directly (and performing
    device ioctl with hard-coded constants, which is prone to breakage)
    you should normally use the `Zvbi.Capture`_ class which does that work
    for you.  Using the `Zvbi.DvbDemux`_ class directly only is useful
    when receiving a stream from other sources (e.g. via socket from
    proxy on a remote host).

Authors
=======

The ZVBI Perl interface module (https://metacpan.org/pod/Video::ZVBI)
was written by T. Zoerner <tomzo@sourceforge.net> starting March 2006
for the Teletext EPG grabber accompanying nxtvepg
(http://nxtvepg.sourceforge.net/). The Perl module was ported to Python
in April 2020. Its official home is at https://pypi.org/project/Zvbi/

The module is based on the libzvbi library, mainly written and maintained
by Michael H. Schimek (2000-2007) and Inaki Garcia Etxebarria (2000-2001),
which in turn is based on AleVT 1.5.1 by Edgar Toernig (1998-1999).
See also http://zapping.sourceforge.net/

License
=======

Copyright (C) 2006-2020 T. Zoerner.

Parts of the descriptions in this man page are copied from the
"libzvbi" documentation, licensed under the GNU General Public
License version 2 or later. The respective copyright is by the following:

* Copyright (C) 2000-2007 Michael H. Schimek,
* Copyright (C) 2000-2001 Inaki Garcia Etxebarria,
* Copyright (C) 2003-2004 Tom Zoerner.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but **without any warranty**; without even the implied warranty of
**merchantability** or **fitness for a particular purpose**.  See the
*GNU General Public License* for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
