LINUX MEDIA INFRASTRUCTURE API

Table of Contents

Introduction

I. Video for Linux Two API Specification

1. Common API Elements

Opening and Closing Devices

Device Naming

Related Devices

Multiple Opens

Shared Data Streams

Functions

Querying Capabilities

Application Priority

Video Inputs and Outputs

Audio Inputs and Outputs

Tuners and Modulators

Tuners

Modulators

Radio Frequency

Video Standards

User Controls

Extended Controls

Introduction

The Extended Control API

Enumerating Extended Controls

Creating Control Panels

MPEG Control Reference

Camera Control Reference

FM Transmitter Control Reference

Data Formats

Data Format Negotiation

Image Format Enumeration

Image Cropping, Insertion and Scaling

Cropping Structures

Scaling Adjustments

Examples

Streaming Parameters

2. Image Formats

Standard Image Formats

Colorspaces

Indexed Format

RGB Formats

Packed RGB formats — Packed RGB formats

V4L2_PIX_FMT_SBGGR8 ('BA81') — Bayer RGB format

V4L2_PIX_FMT_SGBRG8 ('GBRG') — Bayer RGB format

V4L2_PIX_FMT_SGRBG8 ('GRBG') — Bayer RGB format

V4L2_PIX_FMT_SBGGR16 ('BYR2') — Bayer RGB format

YUV Formats

Packed YUV formats — Packed YUV formats

V4L2_PIX_FMT_GREY ('GREY') — Grey-scale image

V4L2_PIX_FMT_Y16 ('Y16 ') — Grey-scale image

V4L2_PIX_FMT_YUYV ('YUYV') — Packed format with ½ horizontal chroma resolution, also known as YUV 4:2:2

V4L2_PIX_FMT_UYVY ('UYVY') — Variation of V4L2_PIX_FMT_YUYV with different order of samples in memory

V4L2_PIX_FMT_YVYU ('YVYU') — Variation of V4L2_PIX_FMT_YUYV with different order of samples in memory

V4L2_PIX_FMT_VYUY ('VYUY') — Variation of V4L2_PIX_FMT_YUYV with different order of samples in memory

V4L2_PIX_FMT_Y41P ('Y41P') — Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1

V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12') — Planar formats with ½ horizontal and vertical chroma resolution, also known as YUV 4:2:0

V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9') — Planar formats with ¼ horizontal and vertical chroma resolution, also known as YUV 4:1:0

V4L2_PIX_FMT_YUV422P ('422P') — Format with ½ horizontal chroma resolution, also known as YUV 4:2:2. Planar layout as opposed to V4L2_PIX_FMT_YUYV

V4L2_PIX_FMT_YUV411P ('411P') — Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1. Planar layout as opposed to V4L2_PIX_FMT_Y41P

V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21') — Formats with ½ horizontal and vertical chroma resolution, also known as YUV 4:2:0. One luminance and one chrominance plane with alternating chroma samples as opposed to V4L2_PIX_FMT_YVU420

V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61') — Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2. One luminance and one chrominance plane with alternating chroma samples as opposed to V4L2_PIX_FMT_YVU420

Compressed Formats

Reserved Format Identifiers

3. Input/Output

Read/Write

Streaming I/O (Memory Mapping)

Streaming I/O (User Pointers)

Asynchronous I/O

Buffers

Timecodes

Field Order

4. Interfaces

Video Capture Interface

Querying Capabilities

Supplemental Functions

Image Format Negotiation

Reading Images

Video Overlay Interface

Querying Capabilities

Supplemental Functions

Setup

Overlay Window

Enabling Overlay

Video Output Interface

Querying Capabilities

Supplemental Functions

Image Format Negotiation

Writing Images

Video Output Overlay Interface

Querying Capabilities

Framebuffer

Overlay Window and Scaling

Enabling Overlay

Codec Interface

Effect Devices Interface

Raw VBI Data Interface

Querying Capabilities

Supplemental Functions

Raw VBI Format Negotiation

Reading and writing VBI images

Sliced VBI Data Interface

Querying Capabilities

Supplemental Functions

Sliced VBI Format Negotiation

Reading and writing sliced VBI data

Sliced VBI Data in MPEG Streams

Teletext Interface

Radio Interface

Querying Capabilities

Supplemental Functions

Programming

RDS Interface

Querying Capabilities

Reading RDS data

5. V4L2 Driver Programming

6. Libv4l Userspace Library

Introduction

libv4lconvert

libv4l1

libv4l2

v4l1compat.so wrapper library

7. Changes

Differences between V4L and V4L2

Opening and Closing Devices

Querying Capabilities

Video Sources

Tuning

Image Properties

Audio

Frame Buffer Overlay

Cropping

Reading Images, Memory Mapping

Reading Raw VBI Data

Miscellaneous

Changes of the V4L2 API

Early Versions

V4L2 Version 0.16 1999-01-31

V4L2 Version 0.18 1999-03-16

V4L2 Version 0.19 1999-06-05

V4L2 Version 0.20 (1999-09-10)

V4L2 Version 0.20 incremental changes

V4L2 Version 0.20 2000-11-23

V4L2 Version 0.20 2002-07-25

V4L2 in Linux 2.5.46, 2002-10

V4L2 2003-06-19

V4L2 2003-11-05

V4L2 in Linux 2.6.6, 2004-05-09

V4L2 in Linux 2.6.8

V4L2 spec erratum 2004-08-01

V4L2 in Linux 2.6.14

V4L2 in Linux 2.6.15

V4L2 spec erratum 2005-11-27

V4L2 spec erratum 2006-01-10

V4L2 spec erratum 2006-02-03

V4L2 spec erratum 2006-02-04

V4L2 in Linux 2.6.17

V4L2 spec erratum 2006-09-23 (Draft 0.15)

V4L2 in Linux 2.6.18

V4L2 in Linux 2.6.19

V4L2 spec erratum 2006-10-12 (Draft 0.17)

V4L2 in Linux 2.6.21

V4L2 in Linux 2.6.22

V4L2 in Linux 2.6.24

V4L2 in Linux 2.6.25

V4L2 in Linux 2.6.26

V4L2 in Linux 2.6.27

V4L2 in Linux 2.6.28

V4L2 in Linux 2.6.29

V4L2 in Linux 2.6.30

V4L2 in Linux 2.6.32

Relation of V4L2 to other Linux multimedia APIs

X Video Extension

Digital Video

Audio Interfaces

Experimental API Elements

Obsolete API Elements

A. Function Reference

V4L2 close() — Close a V4L2 device

V4L2 ioctl() — Program a V4L2 device

ioctl VIDIOC_CROPCAP — Information about the video cropping and scaling abilities

ioctl VIDIOC_DBG_G_CHIP_IDENT — Identify the chips on a TV card

ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER — Read or write hardware registers

ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD — Execute an encoder command

ioctl VIDIOC_ENUMAUDIO — Enumerate audio inputs

ioctl VIDIOC_ENUMAUDOUT — Enumerate audio outputs

ioctl VIDIOC_ENUM_FMT — Enumerate image formats

ioctl VIDIOC_ENUM_FRAMESIZES — Enumerate frame sizes

ioctl VIDIOC_ENUM_FRAMEINTERVALS — Enumerate frame intervals

ioctl VIDIOC_ENUMINPUT — Enumerate video inputs

ioctl VIDIOC_ENUMOUTPUT — Enumerate video outputs

ioctl VIDIOC_ENUMSTD — Enumerate supported video standards

ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO — Query or select the current audio input and its attributes

ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT — Query or select the current audio output

ioctl VIDIOC_G_CROP, VIDIOC_S_CROP — Get or set the current cropping rectangle

ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL — Get or set the value of a control

ioctl VIDIOC_G_ENC_INDEX — Get meta data about a compressed video stream

ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS — Get or set the value of several controls, try control values

ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF — Get or set frame buffer overlay parameters

ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT — Get or set the data format, try a format

ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY — Get or set tuner or modulator radio frequency

ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT — Query or select the current video input

ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP

ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR — Get or set modulator attributes

ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT — Query or select the current video output

ioctl VIDIOC_G_PARM, VIDIOC_S_PARM — Get or set streaming parameters

ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY — Query or request the access priority associated with a file descriptor

ioctl VIDIOC_G_SLICED_VBI_CAP — Query sliced VBI capabilities

ioctl VIDIOC_G_STD, VIDIOC_S_STD — Query or select the video standard of the current input

ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER — Get or set tuner attributes

ioctl VIDIOC_LOG_STATUS — Log driver status information

ioctl VIDIOC_OVERLAY — Start or stop video overlay

ioctl VIDIOC_QBUF, VIDIOC_DQBUF — Exchange a buffer with the driver

ioctl VIDIOC_QUERYBUF — Query the status of a buffer

ioctl VIDIOC_QUERYCAP — Query device capabilities

ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU — Enumerate controls and menu control items

ioctl VIDIOC_QUERYSTD — Sense the video standard received by the current input

ioctl VIDIOC_REQBUFS — Initiate Memory Mapping or User Pointer I/O

ioctl VIDIOC_S_HW_FREQ_SEEK — Perform a hardware frequency seek

ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF — Start or stop streaming I/O

V4L2 mmap() — Map device memory into application address space

V4L2 munmap() — Unmap device memory

V4L2 open() — Open a V4L2 device

V4L2 poll() — Wait for some event on a file descriptor

V4L2 read() — Read from a V4L2 device

V4L2 select() — Synchronous I/O multiplexing

V4L2 write() — Write to a V4L2 device

B. Video For Linux Two Header File

C. Video Capture Example

D. Video Grabber example using libv4l

List of Types

References

II. LINUX DVB API

8. Introduction

What you need to know

History

Overview

Linux DVB Devices

API include files

9. DVB Frontend API

Frontend Data Types

frontend type

frontend capabilities

frontend information

diseqc master command

diseqc slave reply

diseqc slave reply

SEC continuous tone

SEC tone burst

frontend status

frontend parameters

frontend events

Frontend Function Calls

open()

close()

FE_READ_STATUS

FE_READ_BER

FE_READ_SNR

FE_READ_SIGNAL_STRENGTH

FE_READ_UNCORRECTED_BLOCKS

FE_SET_FRONTEND

FE_GET_FRONTEND

FE_GET_EVENT

FE_GET_INFO

FE_DISEQC_RESET_OVERLOAD

FE_DISEQC_SEND_MASTER_CMD

FE_DISEQC_RECV_SLAVE_REPLY

FE_DISEQC_SEND_BURST

FE_SET_TONE

FE_SET_VOLTAGE

FE_ENABLE_HIGH_LNB_VOLTAGE

ISDB-T frontend

Parameters that are common with DVB-T and ATSC

ISDB-T only parameters

10. DVB Demux Device

Demux Data Types

dmx_output_t

dmx_input_t

dmx_pes_type_t

dmx_event_t

dmx_scrambling_status_t

struct dmx_filter

struct dmx_sct_filter_params

struct dmx_pes_filter_params

struct dmx_event

struct dmx_stc

Demux Function Calls

open()

close()

read()

write()

DMX_START

DMX_STOP

DMX_SET_FILTER

DMX_SET_PES_FILTER

DMX_SET_BUFFER_SIZE

DMX_GET_EVENT

DMX_GET_STC

11. DVB Video Device

Video Data Types

video_format_t

video_display_format_t

video stream source

video play state

struct video_event

struct video_status

struct video_still_picture

video capabilities

video system

struct video_highlight

video SPU

video SPU palette

video NAVI pack

video attributes

Video Function Calls

open()

close()

write()

VIDEO_STOP

VIDEO_PLAY

VIDEO_FREEZE

VIDEO_CONTINUE

VIDEO_SELECT_SOURCE

VIDEO_SET_BLANK

VIDEO_GET_STATUS

VIDEO_GET_EVENT

VIDEO_SET_DISPLAY_FORMAT

VIDEO_STILLPICTURE

VIDEO_FAST_FORWARD

VIDEO_SLOWMOTION

VIDEO_GET_CAPABILITIES

VIDEO_SET_ID

VIDEO_CLEAR_BUFFER

VIDEO_SET_STREAMTYPE

VIDEO_SET_FORMAT

VIDEO_SET_SYSTEM

VIDEO_SET_HIGHLIGHT

VIDEO_SET_SPU

VIDEO_SET_SPU_PALETTE

VIDEO_GET_NAVI

VIDEO_SET_ATTRIBUTES

12. DVB Audio Device

Audio Data Types

audio_stream_source_t

audio_play_state_t

audio_channel_select_t

struct audio_status

struct audio_mixer

audio encodings

struct audio_karaoke

audio attributes

Audio Function Calls

open()

close()

write()

AUDIO_STOP

AUDIO_PLAY

AUDIO_PAUSE

AUDIO_SELECT_SOURCE

AUDIO_SET_MUTE

AUDIO_SET_AV_SYNC

AUDIO_SET_BYPASS_MODE

AUDIO_CHANNEL_SELECT

AUDIO_GET_STATUS

AUDIO_GET_CAPABILITIES

AUDIO_CLEAR_BUFFER

AUDIO_SET_ID

AUDIO_SET_MIXER

AUDIO_SET_STREAMTYPE

AUDIO_SET_EXT_ID

AUDIO_SET_ATTRIBUTES

AUDIO_SET_KARAOKE

13. DVB CA Device

CA Data Types

ca_slot_info_t

ca_descr_info_t

ca_cap_t

ca_msg_t

ca_descr_t

CA Function Calls

open()

close()

14. DVB Network API

DVB Net Data Types

15. Kernel Demux API

Kernel Demux Data Types

dmx_success_t

TS filter types

dmx_ts_pes_t

demux_demux_t

Demux directory

Demux Directory API

dmx_register_demux()

dmx_unregister_demux()

dmx_get_demuxes()

Demux API

open()

close()

write()

allocate_ts_feed()

release_ts_feed()

allocate_section_feed()

release_section_feed()

descramble_mac_address()

descramble_section_payload()

add_frontend()

remove_frontend()

get_frontends()

connect_frontend()

disconnect_frontend()

Demux Callback API

dmx_ts_cb()

dmx_section_cb()

TS Feed API

set()

start_filtering()

stop_filtering()

Section Feed API

set()

allocate_filter()

release_filter()

start_filtering()

stop_filtering()

16. Examples

Tuning

The DVR device

III. Other API's used by media infrastructure drivers

17. Remote Controllers

Introduction

Changing default Remote Controller mappings

E. GNU Free Documentation License

0. PREAMBLE

1. APPLICABILITY AND DEFINITIONS

2. VERBATIM COPYING

3. COPYING IN QUANTITY

4. MODIFICATIONS

5. COMBINING DOCUMENTS

6. COLLECTIONS OF DOCUMENTS

7. AGGREGATION WITH INDEPENDENT WORKS

8. TRANSLATION

9. TERMINATION

10. FUTURE REVISIONS OF THIS LICENSE

Addendum