SIP channel name uniqueness
[asterisk/asterisk.git] / doc / video_console.txt
1         --- VIDEO CONSOLE SUPPORT IN ASTERISK ---
2
3 Some console drivers (at the moment chan_oss.so) can be built with
4 support for sending and receiving video.  In order to have this
5 working you need to perform the following steps:
6
7 +++ Enable building the video_console support +++
8
9     The simplest way to do it is add this one line to channels/Makefile:
10
11     chan_oss.so: _ASTCFLAGS+=-DHAVE_VIDEO_CONSOLE
12
13 +++ Install prerequisite packages +++
14
15   The video_console support relies on the presence of SDL, SDL_image
16   and ffmpeg libraries, and of course on the availability of X11
17
18   On Linux, these are supplied by
19
20         libncurses-dev,
21         libsdl1.2-dev, libsdl-image1.2-dev
22         libavcodec-dev, libswcale-dev
23
24   On FreeBSD, you need the following ports:
25
26         multimedia/ffmpeg (2007.10.04)
27         devel/sdl12  graphics/sdl_image
28
29 +++ Build and install asterisk with all the above +++
30
31   Make sure you do a 'make clean' and run configure again after you
32   have installed the required packages, to make sure that the required
33   pieces are found.
34     Check that chan_oss.so is generated and correctly installed.
35
36 +++ Update configuration files +++
37
38   Video support requires explicit configuration as described below:
39   == oss.conf ==
40     You need to set various parameters for video console, the easiest
41     way is to uncomment the following line in oss.conf by removing the
42     leading ';'
43
44         ;[general](+,my_video,skin2)
45
46     You also need to manually copy the two files
47
48         images/kpad2.jpg images/font.png
49
50     into the places specified in oss.conf, which in the sample are set to
51
52             keypad = /tmp/kpad2.jpg
53             keypad_font = /tmp/font.png
54
55     other configuration parameters are described in oss.conf.sample
56
57   == sip.conf ==
58     To actually run a call using SIP (the same probably applies to iax.conf)
59     you need to enable video support as following
60
61         [general](+)
62                 videosupport=yes
63                 allow=h263      ; this or other video formats   
64                 allow=h263p     ; this or other video formats
65
66     you can add other video formats e.g. h261, h264, mpeg if they are
67     supported by your version of libavcodec.
68
69
70 +++ RUN THE PROGRAM +++
71
72    run asterisk in console mode e.g. asterisk -vdc
73
74    If video console support has been successfully compiled in, then
75    you will see the "console startgui" command available on the CLI`
76    interface. Run the command, and you should see a window like this:
77
78         http://info.iet.unipi.it/~luigi/asterisk_video_console.jpg
79
80    To exit from this window, in the console run "console stopgui".
81    If you want to start a video call, you need to configure your dialplan
82    so that you can reach (or be reachable) by a peer who can support video.
83    Once done, a video call is the same as an ordinary call:
84    "console dial ...", "console answer", "console hangup" all work the same.
85    To use the GUI, and also configure video sources, see the next section.
86
87 +++ VIDEO SOURCES +++
88
89   Video sources are declared with the "videodevice=..." lines in oss.conf
90   where the ... is the name of a device (e.g. /dev/video0 ...) or a
91   string starting with X11 which identifies one instance of an X11 grabber.
92   You can have up to 9 sources, displayed in thumbnails in the gui, and
93   select which one to transmit, possibly using Picture-in-Picture.
94
95   For webcams, the only control you have is the image size and frame
96   rate (which at the moment is the same for all video sources).
97   X11 grabbers capture a region of the X11 screen (it can contain
98   anything, even a live video) and use it as the source.
99   The position of the grab region can be configured using the GUI below
100   independently for each video source.
101
102   The actual video sent to the remote side is the device selected as
103   "primary" (with the mouse, see below), possibly with a small
104   'Picture-in-Picture' of the "secondary" device (all selectable
105   with the mouse).
106
107 +++ GUI COMMANDS AND VIDEO SOURCES +++
108
109 (most of the text below is taken from channels/console_gui.c)
110
111 The GUI is made of 4 areas: remote video on the left, local video
112 on the right, keypad with all controls and text windows in the
113 center, and source device thumbnails on the top.  The top row is
114 not displayed if no devices are specified in the config file.
115
116      ________________________________________________________________
117     |  ______   ______   ______   ______   ______   ______   ______  |
118     | | tn.1 | | tn.2 | | tn.3 | | tn.4 | | tn.5 | | tn.6 | | tn.7 | |
119     | |______| |______| |______| |______| |______| |______| |______| |
120     |  ______   ______   ______   ______   ______   ______   ______  |
121     | |______| |______| |______| |______| |______| |______| |______| |
122     |  _________________    __________________    _________________  |
123     | |                 |  |                  |  |                 | |
124     | |                 |  |                  |  |                 | |
125     | |                 |  |                  |  |                 | |
126     | |   remote video  |  |                  |  |   local video   | |
127     | |                 |  |                  |  |          ______ | |
128     | |                 |  |      keypad      |  |         |  PIP || |
129     | |                 |  |                  |  |         |______|| |
130     | |_________________|  |                  |  |_________________| |
131     |                      |                  |                      |
132     |                      |                  |                      |
133     |                      |__________________|                      |
134     |________________________________________________________________|
135
136
137 The central section is built using an image (jpg, png, maybe gif too)
138 for the skin and other GUI elements.  Comments embedded in the image
139 indicate to what function each area is mapped to.
140 Another image (png with transparency) is used for the font.
141
142 Mouse and keyboard events are detected on the whole surface, and
143 handled differently according to their location:
144 - center/right click on the local/remote window are used to resize
145   the corresponding window;
146 - clicks on the thumbnail start/stop sources and select them as
147   primary or secondary video sources;
148 - drag on the local video window are used to move the captured
149   area (in the case of X11 grabber) or the picture-in-picture position;
150 - keystrokes on the keypad are mapped to the corresponding key;
151   keystrokes are used as keypad functions, or as text input
152   if we are in text-input mode.
153 - drag on some keypad areas (sliders etc.) are mapped to the
154   corresponding functions (mute/unmute audio and video,
155   enable/disable Picture-in-Picture, freeze the incoming video,
156   dial numbers, pick up or hang up a call, ...)
157
158 ------------------------------------------------------------------------
159 --- $Id $---