
TaniDVR
A tool for DVRs based on the DVR-IP protocol.

Copyright (c) 2011-2012 Daniel Mealha Cabrita
Available under the GNU GPL v3 license (see "COPYING" file).



What is TaniDVR?
----------------

TaniDVR includes a CLI tool 'tanidvr' for accessing DVRs used for CCTV
surveillance systems based on the DVR-IP protocol (port 37777/TCP).

Those are quite inexpensive Linux-based OEM DVRs made available by several
distinct brands around the world.
All those DVRs, regardless their branding, are produced by this company:
Zhejiang Dahua Technology Co., Ltd.

Unfortunately those DVRs do not come with Un*x-compatible (Linux, *BSD..)
clients, and its web interface only works with a certain web browser for a
certain proprietary OS.

So now you can finally access (watch, record) the videos from such DVRs
from a proper OS.



Is my DVR compatible?
---------------------

If your DVR works with the DVR-IP protocol it is expected to work.

If you want to check whether your DVR supports that, you may verify
if your DVR is listening to the port 37777/TCP (99% of cases).
Those DVRs are advertised as having an embedded Linux running, support
an internal SATA HD, support audio sampling etc and there are models
with 4, 8 and 16 channels (and possibly other variations).

Those DVRs are sold under a number of brands, including:

Apollo
Acorn F&S
C2Max
DVR365
GWave
Intelbras
IntelliPix
Mace S. P.
New Surway
NextVision
Q-See
WatchNet
etc etc etc

TaniDVR is confirmed to work with the following DVR:
Intelbras VD 8E 240

Some DVRs with old firmware may have compatibility problems
due to old implementations of Dahua's own DVR-IP protocol.
Such problems may (or may not) be solved with firmware upgrade.



How do I use 'tanidvr'?
-----------------------

Some examples:

Display the available options:
$ tanidvr --help

Show some information about the DVR:
$ tanidvr -m 0 -t 192.168.0.12 -u admin -w secret1234

Record a video to a file:
$ tanidvr -m 1 -t 192.168.0.12 -u admin -w secret1234 -c 2 -f camera2.mkv

Play the video in realtime with an external player:
$ tanidvr -m 1 -t 192.168.0.12 -u admin -w secret1234 -c 2 | mplayer -cache 32 - 2>/dev/null



'dhav2mkv' tool (DHAV video to MKV format converter)
----------------------------------------------------

'dhav2mkv' is a standalone tool which converts DHAV(H.264) video to MKV(H.264) video.
The routines are the same as the ones used by 'tanidvr' (when the chosen
output container format is MKV, which is the default mode), thus this tool
is _redundant_ is fed directly from tanidvr (from a pipe, for ex.).

dhav2mkv _only_ operates at media container level, thus the H.264 data is _exactly_
as provided by the DVR (with all its bugs).

dhav2mkv _requires_ the channel data to be specified.
This may look counter-intuitive, but it is necessary. The reasons being:

- DHAV is inherently a (though rather primitive) multiplexing video format,
  what makes finding multi-channel video files a possibility.
- The DHAV format itself does not provide explicit information about which channels
  do (or may) appear. Also, a new channel stream may start from the middle
  of the DHAV stream without warning.
- Future developments of TaniDVR may take advantage of this DHAV characteristic
  to aggregate multiple streams into the same stream.


Cases for using dhav2mkv:

- To convert already-existing DHAV files to MKV.
  Those files may be tanidvr-generated or generated by the software included
  with the DVR itself (due to legacy, or by choice).
  --
  DHAV files are only (currently) playable with the software included with
  the DVR, while MKV is a modern, open and commonly supported container format.
  Using a standard container also allows the video to be _recompressed_ for
  better storage usage.

- To create a video hub (a video repeater), propagating DHAV media which,
  at the end-point, is converted to MKV.
  --
  The DVR itself supports a very limited number of simultaneous connections
  (usually slighty more than hardware channels). Also, near the maximum
  active connections the DVR tends to be even more unstable. Direct
  connections to the DVR should be kept to essencial minimum.
  --
  dhav2mkv allows the conversion of ongoing DHAV video (doing that with
  MKV is not viable for technical reasons). Any stream starting point
  (down to byte granularity) is acceptable. Also, temporary source
  interruption with lost/corrupted data suffers automatic resync
  (what is also done by 'tanidvr', when outputting MKV data).
  --
  A simple media hub may be implemented with existing complementary
  software such as ncat (from nmap project) with its '--broker' option.


Some examples:

Convert an existing DHAV file (with channel 5 data) to MKV:
$ dhav2mkv -c 5 -i MyVideo.dhav -o MyVideo.mkv

Used dhav2mkv instead of tanidvr's internal routines
(what is POINTLESS, and shown only for didactic purposes):
$ tanidvr -n 0 -m 1 -t 192.168.0.12 -u admin -w secret1234 -c 2 | dhav2mkv -c 2 > channel_2_video.mkv

Simple (and _insecure_ ; do NOT implement as-is) media server and some clients:
(server at 192.168.20.1)
$ tanidvr -n 0 -m 1 -t 192.168.0.12 -u admin -w secret1234 -c 5 | ncat --broker -l 192.168.20.1 2000
(clients ; same/other host)
$ ncat --recv-only 192.168.20.1 2000 | dhav2mkv -c 5 | mplayer -cache 32 -
$ ncat --recv-only 192.168.20.1 2000 | dhav2mkv -c 5 > channel_5_realtime_backup.mkv
$ ncat --recv-only 192.168.20.1 2000 > channel_5_realtime_backup.dhav



(text ends here)

