Hwp_HTTPStreamer

httpstreamer.hwp
================

This plugin enables Hollywood to open and stream files from HTTP sources as if
they were stored on a local drive. Once this plugin has been activated, all
Hollywood functions that deal with files will "automagically" be able to open
files from HTTP sources as well.

httpstreamer.hwp uses a sophisticated multi-threaded design for highly efficient
HTTP streaming. Each HTTP connection is managed by a dedicated thread for
optimal performance. The plugin also supports Hollywood 6.0's new streaming APIs
which means that you will be able to stream audio and video files from HTTP
sources with plugins like avcodec.hwp.


Requirements
============

This plugin requires at least Hollywood 6.0 since it uses the file adapter and
streaming APIs introduced with Hollywood 6.0.

For video and audio streaming through avcodec.hwp, you need at least version 1.3
of the avcodec.hwp plugin.


Usage
=====

There are two ways to use this plugin: You can either activate the plugin
globally by ()REQUIRE-ing it. To do this, simply put the following preprocessor
command at the top of your script:

    ()REQUIRE "httpstreamer"

If you activate the plugin via ()REQUIRE, it will become globally available and
all ensuing commands that deal with files will support the opening of files from
HTTP sources. For example, you could do something like this then:

    LoadBrush(1, "http://www.example.com/testpicture.jpg")

If you only need to open very few files from HTTP sources, you can also choose
to not activate the plugin globally via ()REQUIRE but simply use the "Adapter"
tag offered by most Hollywood commands to tell the respective Hollywood command
to open the file using the httpstreamer.hwp plugin. Here is an example:

    LoadBrush(1, "http://www.example.com/testpicture.jpg", {Adapter =
"httpstreamer"})

By using the "Adapter" tag, LoadBrush() is told to open the specified file using
the specified adapter, which is "httpstreamer" in our case. Thus, the "Adapter"
tag allows you to use this plugin even without having ()REQUIRE-d it first. 

Keep in mind that all files declared in the preprocessor commands are linked
automatically into your applet or executable when Hollywood is in compile mode.
Thus, if you do the following, the file will be downloaded and linked to your
applet or executable:

    ()BRUSH 1, "http://www.example.com/testpicture.jpg"
    
This means that your applet or executable will not download the file any more
but they will use a copy of the file that has been linked into the applet or
executable! If you want the applet or executable to always use the copy on the
HTTP server, you have to make sure that the file is never linked to the applet
or executable. This can be achieved by setting the "Link" tag to FALSE:

    ()BRUSH 1, "http://www.example.com/testpicture.jpg", {Link = False}
    
When done like this, Hollywood will never link the file into your applet or
executable. Instead, it will always be downloaded from the given URL.    
    

Options
=======

httpstreamer.hwp supports several options which can either be passed to
()REQUIRE or to the httpstreamer.SetConfig() command. Note that ()REQUIRE
expects a table which can contain multiple options at once whereas
httpstreamer.SetConfig() only accepts a single option at a time.

The following options are currently available:

Fail404:
This tag specifies whether or not httpstreamer.hwp should fail with a "file not
found" error when you pass a URL that points to a non-existent file. Normally,
when you request a non-existent file, HTTP servers will generate a special HTML
page with a "404 - file not found" error, and send that to you instead. So you
will always be getting a file even if you are requesting a non-existent file
which can be confusing. If you really want this behaviour, set this tag to
FALSE. Then httpstreamer.hwp will never fail for any HTTP files and will always
deliver an error page in case of a non-existent file. By default, this tag is
set to TRUE which means that no error page is generated and httpstreamer.hwp
will fail to open non-existent files.

Redir:
Specifies whether or not the web server is allowed to redirect you to a new URL.
Thisdefaults to TRUE which means that redirection is allowed.

Timeout:
This tag allows you to set a connection timeout in milliseconds. The default is
10000 which means that httpstreamer.hwp will timeout in case the server doesn't
reply within an interval of 10 seconds.

Proxy:
You can specify a proxy server here that should be used when making connections.
By default, httpstreamer.hwp doesn't use any proxy server.

UserAgent:
This tag allows you to change the user agent that httpstreamer.hwp sends to the
target server. This is useful with servers that refuse to cooperate with unknown
user agents. By default, httpstreamer.hwp will send "HTTPStreamer.hwp" in the
user agent field of HTTP requests.

TmpFileThreshold:
When requesting larger files, httpstreamer.hwp will use a temporary file for its
buffer instead of memory. This tag allows you to specify a threshold value in
bytes that defines when httpstreamer.hwp should use a temporary file instead of
a memory buffer.
This defaults to 16277216 bytes which means that all files larger than 16 MB
will be buffered on disk whereas all files smaller than 16 MB will be buffered
in memory.

RamFileThreshold:
This is only supported on AmigaOS and compatibles. When using temporary file
buffering (see the documentation of "TmpFileThreshold" above), this tag allows
you to set a threshold value that defines whether the temporary file should be
created in RAM disk or on your hard drive. Whenever the temporary file is bigger
than the threshold value specified here, it will be created on your hard drive.
Otherwise it will be created in T: on your RAM disk. Obviously, this tag must be
set to at least the value of "TmpFileThreshold". It defaults 33554432 bytes on
AmigaOS 3 and 104857600 bytes on all other AmigaOS compatibles. This means that
on AmigaOS 3 all temporary files smaller than 32 MB will be written to T:
whereas on all other systems all temporary files smaller than 100 MB will be
written to T:.

IOBufSize:
This tag allows you to set the IO buffering size. It's normally not necessary to
tinkerwith this. Defaults to 16384 bytes.

SetStreaming:
This tag allows you to set whether httpstreamer.hwp should inform Hollywood that
its file handles are actually streams. By default, httpstreamer.hwp does so.
This allows Hollywood to try to avoid operations that are inefficient on
streaming sources like excessive seeking operations. If you set this tag to
FALSE, Hollywood won't be made aware that the file handles managed by
httpstreamer.hwp are actually streams. This might entail undesirable
consequences because Hollywood might try to seek the file handle to the end and
since the HTTP protocol doesn't easily support direct byte seeking, the seek
operation has to be emulated which can be really expensive.
Seeking to the end of a HTTP stream for instance means that httpstreamer.hwp
will have to download the entire file before it can continue! Thus, you normally
won't want to set this tag to FALSE but keep it to TRUE, which is the default.

SetNoSeek:
If this tag is set to TRUE, httpstreamer.hwp won't support seeking on its file
handles. Note that if you set this tag to TRUE, several file format handlers
which depend on the seek functionality might stop working. That's why it's
recommended to leave this tag at its default value, which is FALSE.

Here is an example of how to use these tags:

    ()REQUIRE "httpstreamer", {UserAgent = "Firefox", Timeout = 20000}

                -OR-

    httpstreamer.SetConfig("UserAgent", "Firefox")
    httpstreamer.SetConfig("Timeout", 20000)

Using httpstreamer.SetConfig() is especially useful if you do not want to
()REQUIRE
the plugin.


Troubleshooting
===============

You have to be careful when using HTTP URLs in preprocessor commands because
when Hollywood is in compile mode, it will link all files declared in the
preprocessor commands to the applet or executable by default. This means that
Hollywood will download all files declared in the preprocessor commands and link
them which isprobably not what you want in that case. You probably want
Hollywood to always use the copy from the server instead of a linked copy. See
the section "Usage" above for information on how you can achieve this.


History
=======

Version 1.1:    (25-Mar-17)
- New: Added 64-bit builds for Windows, Linux, and Mac OS
- New: Added support for Hollywood 7.0's help string feature
- Fix: Documentation wrongly documented "http.SetConfig" when it had to be
"httpstreamer.SetConfig"
- New: Added "Encoded" option; when this is set to TRUE using SetConfig(), HTTP
Streamer will expect
  encoded URLs instead of unencoded URLs (requested by Lazar Zoltan)
- Fix: HTTP Streamer didn't handle HTTP redirect requests correctly (reported by
Dominique Vanderveken)

Version 1.0:    (26-Sep-15)
- First release


Future
======

Direct seeking using HTTP range requests would be nice but not all servers
support it.


Bugs
====

Please report any bugs or issues via the Hollywood forums at
http://forums.hollywood-mal.com/


Copyright
=========

This plugin is (C) Copyright 2014-2017 by Andreas Falkenhahn
<andreas()airsoftsoftwair.de>
Refer to the COPYING file in this package for conditions concerning distribution
of this plugin. Visit http://www.hollywood-mal.com/ for more information
on Hollywood and more plugins.