Expiration date/time for .m3u files

[kunikla]

At some point, the feature addressed in Issue #10 will require the plugin to figure out if any other visitors to the website are playing the audio file selected by this visitor. That information could be stored in the database in a table created and used by the StreamOnly plugin. However, the information is already available in the list of .m3u files, if the script that downloads the .mp3 file does not immediately delete the .m3u file.

The reason the developer who wrote the code on which the StreamOnly script is based chose to have the script delete the file is to keep the directory from getting cluttered with .m3u files. The callback provided to add_mime_display_type(), as described in Issue #6, deletes expired files from any visitor, so we could allow that function to handle cleanup exclusively.

We also have the problem of a user loading a page, generating one or more .m3u files, then waiting a long time before clicking on the audio controls. If we use the existence of the .m3u file to prevent other visitors from listening to those audio files, they could be locked out for a long time. And if another visitor's callback function deletes the .m3u file because it has "expired", the script has no good way to communicate with Omeka why it was unable to download the audio file.

I am proposing the following method for handling the expiration of .m3u files:

1. When the visitor loads the page, the Omeka hook (callback provided to add_mime_display_type()) will delete any expired .m3u files. It will then check to see if any unexpired .m3u files refer to the file this visitor is requesting.
2. If no unexpired .m3u files refer to this file, the hook will output the <audio class='stream-only' src="path/to/script.php?uniqueid"> string. It will also create an appropriate .m3u file.
3. If an unexpired .m3u file exists that refers to the file, the hook will output the string <span class='stream-only'>File will be available at HH:MM:SS</span> string. A timer can be set up with a callback function that replaces the first <span> with a different one: <span class="stream-only">File available, click to request access</span>. Clicking on that "button" will trigger an AJAX request to the server; the appropriate .m3u file will be generated on the server and the DOM will be updated to display the appropriate <audio> HTML element.
4. In a hookAfterFooter() function, when a front end page has an <audio class="stream-only"> HTML element, a Javascript timer will be set up. It will be triggered slightly before the .m3u file expires. Its JavaScript callback routine will replace any <audio class="stream-only"> elements with <span class="stream-only">Access expired, click to request access</span> elements, which can be styled as a button. It will then delete the .m3u files earlier created by the add_mime_display_type() callback function. Clicking on that "button" will trigger an AJAX request to the server; the appropriate .m3u file will be generated on the server and the DOM will be updated to display the appropriate <audio> HTML element.
5. (Optional) The hookAfterFooter() function could set up a JS timer and callback that updates the amount of time until the user could click on a button to request access to the file.

Note 1: All messages will be translatable.

Note 2: The stream-only class will allow the site administrator to style the messages and audio controls as desired.

Note 3: To simplify the above explanation, I wrote it as though a file could only be streamed by one visitor at a time. But we will allow the site administrator to customize how many visitors can stream a file at one time. All code should honor this customization.

Don't you just love event-driven programming? This is going to be the dickens to test. ~Christina

[kunikla]

If the above is too complicated, just before the .m3u file is about to expire, the callback for the JS timer could replace the <audio> element with a message requesting the user to reload the page.

[kunikla]

Pull Request #24 sets up the HTML for the JavaScript routines to update. The "in use" message displayed is:
<span class='so-msg' data-sofile='ddd' data-soexpires='tttttttttt'>
Recording reserved, available in <span class='so-seconds'>sss</span> seconds</span>
where
ddd = File record ID (digits)
tttttttttt = time when reserved status ends (UTC string)
sss = number of seconds until reserved status ends (string of digits)