README.md
1harvid -- HTTP Ardour Video Daemon
2==================================
3
4Harvid decodes still images from movie files and serves them via HTTP.
5
6Its intended use-case is to efficiently provide frame-accurate data and
7act as second level cache for rendering the video-timeline in
8[Ardour](http://ardour.org).
9
10
11Download
12--------
13
14Apart from the source-code and packages from your linux-distributor, binaries
15are available for OSX, Windows and Linux at http://x42.github.com/harvid/ .
16
17
18Usage
19-----
20
21Harvid is a standalone HTTP server, all interaction takes place via HTTP.
22After launching it, simply point a web-browser at http://localhost:1554/
23
24The OSX bundle and window installer come with a shortcut link to launch
25the server. On Linux or with the OSX package, harvid is usually started
26from a terminal by simply typing `harvid`<enter>.
27
28Harvid can also be run directly from the source folder without installing
29it. Get its build-dependencies (see below), run
30
31 make
32 ./src/harvid
33
34When used from ardour, ardour will automatically start the server when
35you open a video. Ardour searches $PATH or asks your for where it can find
36harvid. The easiest way is to simply run:
37
38 sudo make install
39
40Harvid can be launched as system-service (daemonized, chroot, chuid, syslog),
41and listen on specific interfaces only in case you do not want to expose
42access to your movie-collection. However, is no per request access control.
43
44For available options see `harvid --help` or the included man page which
45is also available online at http://x42.github.com/harvid/harvid.1.html
46
47
48Build-dependencies
49------------------
50
51[ffmpeg](http://ffmpeg.org/) is used to decode the movie. The source
52code should be compatible and compile with [libav](https://libav.org/).
53
54For encoding images,
55[libpng](http://www.libpng.org/pub/png/libpng.html)
56and [libjpeg](http://libjpeg.sourceforge.net/) are required.
57
58
59Packaging Information
60---------------------
61
62A good start is to look in the `debian/` folder that comes with the source
63code (it is excluded from source archives via .gitattributes). In particular
64the file `debian/rules` which demonstrates the use of PREFIX and DESTDIR.
65
66
67Internals
68---------
69
70Harvid is highly concurrent makes use of all available CPUs. It will
71spawn multiple decoder processes, keep them available for a reasonable
72time and also cache the video-decoder's output for recurring requests.
73
74
75The cache-size is variable only limited by available memory.
76All images are served from the cache, so even if you are not planning
77to use the built-in frame cache, the cache-size defines the minimum
78number of concurrent connections.
79
80Interface
81---------
82
83The HTTP request interface is documented on the homepage of the server
84itself: http://localhost:1554/
85
86The default request-handler will respond to `/?file=PATH&frame=NUMBER`
87requests. Optionally `&w=NUM` and `&h=NUM` can be used to alter the geometry
88and `&format=FMT` to request specific pixel-formats and/or encodings.
89
90`/index[/PATH]` allows to get a list of available files - either as tree or
91as flat-list with the ?flatindex=1 as recursive list of the server's docroot.
92
93`/info?file=PATH` returns information about the video-file.
94
95Furthermore there are built-in request handlers for status-information,
96server-version and configuration as well as admin-tasks such as flushing
97the cache or closing decoders.
98
99The `&format=FMT` also applies for information requests with
100HTML, JSON, CSV and plain text as available formatting options.
101