Readme: | 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. This defaults 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 tinker with 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 is probably 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.
|