Sensoray Model 2253/953 README
--------------------------

Version 1.2.26

Please see Linux software driver 2253 manual

Release notes:
June 28, 2010:  First release.
Nov 10, 2010:   Audio features added.
Apr 25, 2011:   Output and overlay features added.
May 19, 2011:   Low-latency mode and raw output mode added.
Jul 19, 2011:   Low-latency playback mode added.
Sep 19, 2011:   MPEG transport stream added.
Mar 15, 2012:   New OSD features added.
Jul 17, 2012:   Suspend/resume support.
Feb 20, 2013:   OSD text increased to 160 chars.
Mar 07, 2013:   Firmware updated for model 953 (4-channel capture).
Mar 18, 2013:   VBI Closed caption insertion into H.264 stream.
May 10, 2013:   Raw BGR24 and RGB565 formats added.
June 3, 2013:   MJPEG decode enabled.
Aug 05, 2013:   OSD font support (requires libmagickwand-dev)
Nov 08, 2013:   Added TB support (Model 2253P)
Nov 15, 2013:   Added H264 QP controls.
Apr  9, 2014:   Added crop, pause trigger and freeze frame.
May 18, 2015:   Updated for Linux 3.19.
June 1, 2015:   Added resizer overlay channel 3
Dec  1, 2015:   Added VideoBuf2 support (on 3.6+)
Dec 21, 2015:   Fix for 953.
Jan 20, 2016:   Only use VideoBuf2 when VideoBuf1 is missing
Mar 17, 2016:   Fix queryctrl on newer kernels
May  4, 2016:   Fix null dereference on 4.5 kernel
May 19, 2016:   Fix output packet corruption, H.264 pixel range
May 24, 2016:   Add missing colorspace parameter to format
Aug 19, 2016:   Fix MPEG-2 encoding parameters
Sept 8, 2016:   Make transport stream timestamps interval constant
Sep 29, 2016:   Add field mode encoding 
Mar 10, 2017:   Fix usb_control_msg using non-kernel buffer in driver
                Add overlay/mid2253.c (windows-style API)
Jul 10, 2017:   Add V4L2_CID_AUTOGAIN and V4L2_CID_AUTOBRIGHTNESS
Aug 7,  2018:   Fix some disconnect issues, and overlay bugs.
                Add extended ASCII OSD text patterns.
Mar 22, 2019:   Disable comb filter for PAL
Jun 11, 2019:   Implement audio playback
Oct 25, 2019:   Update driver for Linux v5.1-v5.3
		Add mp4 library for aarch64
Nov 12, 2019:   Force VIDEBUF2 for kernel 5.1.0 to 5.3.3
Jun 12, 2020:   Driver update for kernel 5.4
May  3, 2021:   Driver update for kernel 5.11+
May  4, 2021:   Add V4L2_CID_MPEG_STREAM_PID and PES_ID controls
Nov  3, 2021:   Driver update for kernel 5.14
Dec  1, 2021:   Fix crash with S2253_CID_OSD_MESSAGE, make VIDIOC_S_PARM 
                timeperframe round up to nearest frame rate divider
Mar 21, 2022:   Add MP3 audio encoding.
Nov 18, 2022:   Allow raw output mode to work with V4L2_FIELD_ALTERNATE,
                for a slight reduction in latency.
Jun 14, 2023:   Fix stream flushing in driver, causing every other stream
                instance to stop immediately and return no data.
Aug 19, 2023:   Add deinterlacer algorithm control.
Jun 19, 2024:   Driver update for kernel 6.9
May 16, 2025:   Firmware adds more options for MPEG4 aspect ratio
May 23, 2025:   Fixes crash when remuxing MP4
Apr 16, 2026:   Driver update for new kernel, fix output mode.

Note: H.264 capture concurrent with MPEG-4 capture or playback is 
           not supported in this release.
      MPEG-4 has been observed to have artifacts when width=160.
      BGR24 is broken at width=720.
      MJPEG decode breaks subsequent H264/MPEG4 decode, device 
           must be replugged to recover.


Package contents
----------------
driver/		Contains kernel module source and firmware
demo.py		GUI demo (requires Python and GTK)
capture.c	Command-line capture demo program
playback.c	Command-line playback demo program
overlay/	Video output overlay program and example scripts
mp4/		MP4 muxing helper library
xvdemo.c	Low-latency preview demo using Xv display


Quickstart
----------

To build driver and demo programs:

  make

To install driver into the Linux module dir:

  sudo make install

To load driver manually:
  sudo modprobe s2253
(Note: driver can be loaded automatically by plugging 2253 into usb port)

To unload driver manually:
  sudo rmmod s2253
(Note: pulseaudio daemon may prevent unloading)

A Python + GTK demo is provided:

  ./demo.py


To rebuild demo applications:

  make demo

To run command line capture demo:

./capture -h

To capture jpeg images:
./capture -j

To capture MPEG4 video:
./capture -4 -o output.m4v

To capture h.264 video:
./capture -x -o output.h264

To capture raw UYVY video:
./capture -u -o output.raw

To capture raw YUY2 video:
./capture -y -o output.raw

To playback raw YUY2 stream:
mplayer -rawvideo format=yuy2:w=640:h=480 -demuxer rawvideo output.raw

To preview with mplayer:
mplayer tv:// -tv outfmt=yuy2:width=320:height=240:norm=NTSC:device=/dev/video1
mplayer tv:// -tv outfmt=uyvy:width=320:height=240:norm=NTSC:device=/dev/video1
mplayer tv:// -tv outfmt=mjpg:width=320:height=240:norm=NTSC:device=/dev/video1
note: -tv option mjpeg & quality doesn't work
note: nv12 format doesn't work with latest mplayer version
MPEG4: mplayer tv:// -tv outfmt=0x5634504d:width=640:height=480:norm=NTSC
H264:  mplayer tv:// -tv outfmt=0x34363248:width=640:height=480:norm=NTSC
note: use -v option to see the hex code for the format


Record and play PCM audio on the host:
./srecord -p -r 8000 -o test.pcm
aplay test.pcm -r 8000 -c 2 -f S16_LE

Record and play g.711 audio on the host:
./srecord -g -r 8000 -o test.g711
aplay test.g711 -r 8000 -c 2 -f A_LAW

Record and play pcm audio on the host:
./srecord -p -r 8000 -o test.pcm
aplay test.pcm -r 8000 -c 2 -f S16_LE

Note: Audio is not supported in 1.0.x release.

Audio is presented as an ALSA capture and playback device:

$ arecord -l
**** List of CAPTURE Hardware Devices ****
card 0: s2253 [Sensoray 2253], device 0: s2253 [Sensoray 2253]
  Subdevices: 1/1
  Subdevice #0: subdevice #0

$ arecord -v -D hw:1,0 -f S16_LE > /dev/null

PCM examples:
arecord -v -D hw:1,0 -c 2 -f S16_LE -r 48000 | aplay -f S16_LE -c 2 -r 48000
arecord -v -D hw:1,0 -c 1 -f S16_LE -r 8000 | aplay -f S16_LE -c 1 -r 8000
note: for lowest latency, use --period-time=21333 with arecord

G711 examples:
arecord -v -D hw:1,0 -c 1 -f A_LAW -r 8000 -t raw | aplay -t raw -f A_LAW -c 1 -r 8000
