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

Digital Video (DV) Timings

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

Single- and multi-planar APIs

Multi-planar formats

Calls that distinguish between single and multi-planar APIs

Image Cropping, Insertion and Scaling

Cropping Structures

Scaling Adjustments

Examples

Streaming Parameters

2. Image Formats

Single-planar format structure

Multi-planar format structures

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_SRGGB8 ('RGGB') — Bayer RGB format

V4L2_PIX_FMT_SBGGR16 ('BYR2') — Bayer RGB format

V4L2_PIX_FMT_SRGGB10 ('RG10'), V4L2_PIX_FMT_SGRBG10 ('BA10'), V4L2_PIX_FMT_SGBRG10 ('GB10'), V4L2_PIX_FMT_SBGGR10 ('BG10'), — 10-bit Bayer formats expanded to 16 bits

V4L2_PIX_FMT_SRGGB12 ('RG12'), V4L2_PIX_FMT_SGRBG12 ('BA12'), V4L2_PIX_FMT_SGBRG12 ('GB12'), V4L2_PIX_FMT_SBGGR12 ('BG12'), — 12-bit Bayer formats expanded to 16 bits

YUV Formats

Packed YUV formats — Packed YUV formats

V4L2_PIX_FMT_GREY ('GREY') — Grey-scale image

V4L2_PIX_FMT_Y10 ('Y10 ') — Grey-scale image

V4L2_PIX_FMT_Y12 ('Y12 ') — Grey-scale image

V4L2_PIX_FMT_Y10BPACK ('Y10B') — Grey-scale image as a bit-packed array

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_YUV420M ('YU12M') — Variation of V4L2_PIX_FMT_YUV420 with planes non contiguous in memory.

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_NV12M ('NV12M') — Variation of V4L2_PIX_FMT_NV12 with planes non contiguous in memory.

V4L2_PIX_FMT_NV12MT ('TM12') — Formats with ½ horizontal and vertical chroma resolution. This format has two planes - one for luminance and one for chrominance. Chroma samples are interleaved. The difference to V4L2_PIX_FMT_NV12 is the memory layout. Pixels are grouped in macroblocks of 64x32 size. The order of macroblocks in memory is also not standard.

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

V4L2_PIX_FMT_M420 ('M420') — Format with ½ horizontal and vertical chroma resolution, also known as YUV 4:2:0. Hybrid plane line-interleaved layout.

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

Writing RDS data

RDS datastructures

Event Interface

Sub-device Interface

Controls

Events

Pad-level Formats

Media Bus Formats

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

V4L2 in Linux 2.6.33

V4L2 in Linux 2.6.34

V4L2 in Linux 2.6.37

V4L2 in Linux 2.6.39

Relation of V4L2 to other Linux multimedia APIs

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_DQEVENT — Dequeue event

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_DV_PRESETS — Enumerate supported Digital Video presets

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_DV_PRESET, VIDIOC_S_DV_PRESET — Query or select the DV preset of the current input or output

ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS — Get or set custom DV timings for input or output

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_QUERY_DV_PRESET — Sense the DV preset received by the current input

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

ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL — Enumerate frame intervals

ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE — Enumerate media bus frame sizes

ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE — Enumerate media bus formats

ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP — Get or set the crop rectangle on a subdev pad

ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT — Get or set the data format on a subdev pad

ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL — Get or set the frame interval on a subdev pad

ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT — Subscribe or unsubscribe event

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

FE_SET_FRONTEND_TUNE_MODE

FE_DISHNETWORK_SEND_LEGACY_CMD

FE_GET_PROPERTY/FE_SET_PROPERTY

FE_GET_PROPERTY

FE_SET_PROPERTY

Property types

Parameters that are common to all Digital TV standards

ISDB-T frontend

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

E. DVB Frontend Header File

III. Remote Controller API

17. Remote Controllers

Introduction

Changing default Remote Controller mappings

LIRC Device Interface

Introduction

LIRC read fop

LIRC write fop

LIRC ioctl fop

IV. Media Controller API

18. Media Controller

Introduction

Media device model

F. Function Reference

media open() — Open a media device

media close() — Close a media device

media ioctl() — Control a media device

ioctl MEDIA_IOC_DEVICE_INFO — Query device information

ioctl MEDIA_IOC_ENUM_ENTITIES — Enumerate entities and their properties

ioctl MEDIA_IOC_ENUM_LINKS — Enumerate all pads and links for a given entity

ioctl MEDIA_IOC_SETUP_LINK — Modify the properties of a link

G. 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