README

Copyright (C) 2011 - 2013 by Johns. All Rights Reserved.
Copyright (C) 2018 by pesintta, rofafor.

SPDX-License-Identifier: AGPL-3.0-only

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License.

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 Affero General Public License for more details.

A VA-API output device plugin for VDR.

    o Based on softhddevice by Johns: http://projects.vdr-developer.org/projects/plg-softhddevice
    o Video decoder CPU / VAAPI
    o Video output VAAPI
    o Audio FFMpeg / Alsa / Analog / Digital
    o HDMI/SPDIF pass-through
    o VDR ScaleVideo API
    o Autocrop
    o Grab image (no OSD!)
    o Suspend / Detach
    o Letterbox, Stretch and Center cut-out video display modes

Install:
--------

	git clone https://github.com/pesintta/vdr-plugin-vaapidevice.git
	cd vdr-plugin-vaapidevice
	make
	make install

	You can edit Makefile to enable/disable Alsa support.
	The default is to autodetect as much as possible.

Issues/bugs:
------------

	If any issues or bugs arise, please, open an Github issue here:
	https://github.com/pesintta/vdr-plugin-vaapidevice/issues

	Remember to include your system report into the Github issue by
	the included script:

	export DISPLAY=:0.0
	./generate_system_report.sh

Setup:	environment
------
	Following is supported:

	DISPLAY=:0.0
		x11 display name

	Only if alsa is configured:

	ALSA_DEVICE=default
		alsa PCM device name
	ALSA_PASSTHROUGH_DEVICE=
		alsa pass-though (AC-3,E-AC-3,DTS,...) device name
	ALSA_MIXER=default
		alsa control device name
	ALSA_MIXER_CHANNEL=PCM
		alsa control channel name

Setup: /etc/vdr/setup.conf
------
	Following is supported:

	vaapidevice.MakePrimary = 0
	0 = no change, 1 make vaapidevice primary at start

	vaapidevice.HideMainMenuEntry = 0
	0 = show vaapidevice main menu entry, 1 = hide entry

	vaapidevice.Osd.Width = 0
	0 = auto (=display, unscaled) n = fixed osd size scaled for display
	vaapidevice.Osd.Height = 0
	0 = auto (=display, unscaled) n = fixed osd size scaled for display

	<res> of the next parameters is 576i, 720p, 1080i, 1080p, or 2160p.

	vaapidevice.<res>.Scaling = 0
	0 = normal, 1 = fast, 2 = HQ, 3 = anamorphic

	vaapidevice.<res>.Deinterlace = 0
	0 = disabled, 1 = bob, 2 = weave, 3 = motion adaptive, 4 = motion compensated

	vaapidevice.<res>.Denoise = 0
	0 .. 1000 noise reduction level (0 off, 1000 max)

	vaapidevice.<res>.Sharpness = 0
	-1000 .. 1000 sharpness level (0 off, -1000 max blur,
	    1000 max sharp)

	vaapidevice.<res>.CutTopBottom = 0
	Cut 'n' pixels at at top and bottom of the video picture.

	vaapidevice.<res>.CutLeftRight = 0
	Cut 'n' pixels at at left and right of the video picture.

	vaapidevice.AudioDelay = 0
	+n or -n ms
	delay audio or delay video

	vaapidevice.AudioPassthrough = 0
	0 = none, 1 = PCM, 2 = MPA, 4 = AC-3, 8 = EAC-3, -X disable

	for PCM/AC-3/EAC-3 the pass-through device is used and the audio
	stream is passed undecoded to the output device.
	z.b. 12 = AC-3+EAC-3, 13 = PCM+AC-3+EAC-3
	note: MPA/DTS/TrueHD/... aren't supported yet
	negative values disable passthrough

	vaapidevice.AudioDownmix = 0
	0 = none, 1 = downmix
	Use ffmpeg/libav downmix of AC-3/EAC-3 audio to stereo.

	vaapidevice.AudioSoftvol = 0
	0 = off, use hardware volume control
	1 = on, use software volume control

	vaapidevice.AudioNormalize = 0
	0 = off, 1 = enable audio normalize

	vaapidevice.AudioMaxNormalize = 0
	maximal volume factor/1000 of the normalize filter

	vaapidevice.AudioCompression = 0
	0 = off, 1 = enable audio compression

	vaapidevice.AudioMaxCompression = 0
	maximal volume factor/1000 of the compression filter

	vaapidevice.AudioStereoDescent = 0
	reduce volume level (/1000) for stereo sources

	vaapidevice.AudioBufferTime = 0
	0 = default (336 ms)
	1 - 1000 = size of the buffer in ms

	vaapidevice.AutoCrop.Interval = 0
	0 disables auto-crop
	n each 'n' frames auto-crop is checked.

	vaapidevice.AutoCrop.Delay = 0
	if auto-crop is over 'n' intervals the same, the cropping is
	used.

	vaapidevice.AutoCrop.Tolerance = 0
	if detected crop area is too small, cut max 'n' pixels at top and
	bottom.

	vaapidevice.Background = 0
	32bit RGBA background color
	(Red * 16777216 +  Green * 65536 + Blue * 256 + Alpha)
	or hex RRGGBBAA
	grey 127 * 16777216 + 127 * 65536 + 127 * 256 => 2139062016
	in the setup menu this is entered as (24bit RGB and 8bit Alpha)
	(Red * 65536 +  Green * 256 + Blue)

	vaapidevice.Suspend.Close = 0
	1 suspend closes x11 window, connection and audio device.
	(use svdrpsend plug vaapidevice RESU to resume, if you have no lirc)

	vaapidevice.Suspend.X11 = 0
	1 suspend stops X11 server (not working yet)

	vaapidevice.60HzMode = 0
	0 disable 60Hz display mode
	1 enable 60Hz display mode

	vaapidevice.SoftStartSync = 0
	0 disable soft start of audio/video sync
	1 enable soft start of audio/video sync

	vaapidevice.Video4to3DisplayFormat = 1
	0 pan and scan
	1 letter box
	2 center cut-out

	vaapidevice.VideoOtherDisplayFormat = 1
	0 pan and scan
	1 pillar box
	2 center cut-out

Setup: /etc/vdr/remote.conf
------

	Add "XKeySym." definitions to /etc/vdr/remote.conf to control
	the vdr and plugin with the connected input device.

	fe.
	XKeySym.Up	Up
	XKeySym.Down	Down
	...

	Additional to the x11 input sends the window close button "Close".

	fe.
	XKeySym.Power	Close

Commandline:
------------

	Use vdr -h to see the command line arguments supported by the plugin.

	-a audio_device

	Selects audio output module and device.
	""		to disable audio output
	other		to use alsa audio module (if compiled with alsa
			support)

	-t trace_mode

	Sets the default tracing bitmask for debug message categories. The
	available categories can be found in the "misc.h" header file.

SVDRP:
------

	Use 'svdrpsend plug vaapidevice HELP' to see the SVDRP commands help
	and which are supported by the plugin.

Keymacros:
----------

	See keymacros.conf how to setup the macros.

	This are the supported key sequences:

	@vaapidevice Blue 1 0		disable pass-through
	@vaapidevice Blue 1 1		enable pass-through
	@vaapidevice Blue 1 2		toggle pass-through
	@vaapidevice Blue 1 3		decrease audio delay by 10ms
	@vaapidevice Blue 1 4		increase audio delay by 10ms
	@vaapidevice Blue 1 5		toggle ac3 mixdown
	@vaapidevice Blue 2 0		disable fullscreen
	@vaapidevice Blue 2 1		enable fullscreen
	@vaapidevice Blue 2 2		toggle fullscreen
	@vaapidevice Blue 2 3		disable auto-crop
	@vaapidevice Blue 2 4		enable auto-crop
	@vaapidevice Blue 2 5		toggle auto-crop
	@vaapidevice Blue 3 0		stretch 4:3 to display
	@vaapidevice Blue 3 1		letter box 4:3 in display
	@vaapidevice Blue 3 2		center cut-out 4:3 to display
	@vaapidevice Blue 3 9		rotate 4:3 to display zoom mode
	@vaapidevice Blue 4 0           stretch other aspect ratios to display
	@vaapidevice Blue 4 1           letter box other aspect ratios in display
	@vaapidevice Blue 4 2           center cut-out other aspect ratios to display
	@vaapidevice Blue 4 9           rotate other aspect ratios to display zoom mode
	@vaapidevice Blue 5 0		toggle debug statistics osd

Running:
--------

	Click into video window to toggle fullscreen/window mode, only if you
	have a window manager running.

Requires:
---------
	media-video/vdr (version >=2.2.0)
		Video Disk Recorder - turns a pc into a powerful set top box
		for DVB.
		http://www.tvdr.de/

	media-video/ffmpeg (version >=3.2)
		Complete solution to record, convert and stream audio and
		video. Includes libavcodec and libswresample.
		http://ffmpeg.org

	media-libs/alsa-lib
		Advanced Linux Sound Architecture Library
		http://www.alsa-project.org

	x11-libs/libva (version >=2.0.0)
		Video Acceleration (VA) API for Linux
		http://www.freedesktop.org/wiki/Software/vaapi

	x11-libs/libva-intel-driver (version >=2.0.0)
		HW video decode support for Intel integrated graphics
		http://www.freedesktop.org/wiki/Software/vaapi

	x11-libs/libxcb,
		X C-language Bindings library
		http://xcb.freedesktop.org

	x11-libs/xcb-util,
	x11-libs/xcb-util-wm,
	x11-libs/xcb-util-keysyms
		X C-language Bindings library
		http://xcb.freedesktop.org
		Only versions >= 0.3.8 are good supported

	x11-libs/libX11
		X.Org X11 library
		http://xorg.freedesktop.org