Differences

This shows you the differences between two versions of the page.

--- streaming:lsapidocs [2010/01/18 18:29] – marco
+++ streaming:lsapidocs [2026/05/27 14:01] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+====== Livestreams API documentatie ======
+De site http://livestreams.omroep.nl verzorgt de functionaliteit van de Livestreams API.
+Het doel van de Livestreams API is om aan de hand van een request eventueel na het uitvoeren van een aantal controles een asx of gelijkwaardig uit te serveren waarmee de bezoeker uiteindelijk de stream kan afspelen.
+Een omschrijving van wat er gebeurd tussen de intentie van de bezoeker om een stream te kijken en dat die bezoeker bezig is de stream te bekijken is het volgende:
+  * Bezoeker surft naar de website waar hij een stream wil zien
+  * Bezoeker klikt op een linkje van die website welke verwijst naar livestreams.omroep.nl.  Het linkje op de website kan daarbij indien van toepassing voorzien zijn van anti-deeplink argumenten.
+  * livestreams.omroep.nl controleerd indien nodig het IP adres van de bezoeker op basis van GeoIP.
+  * livestreams.omroep.nl controleerd indien nodig de anti-deeplink argumenten.
+  * livestreams.omroep.nl controleerd of het AS van de bezoeker zijn IP in een overflow constructie zit.
+  * livestreams.omroep.nl serveert een .asx of gelijkwaardig uit met daarin verwijzingen naar streaming servers.  Deze verwijzingen zijn voorzien van nieuwe argumenten welke de uiteindelijke streaming server de kans geven een secundaire anti-deeplink controle te doen.
+  * Bezoeker zijn computer start op basis van de ontvangen .asx verwant een stuk media afspeel software welke de verwijzingen in de .asx verwant probeerd af te spelen.
+  * De streaming server welke het verzoek van de media afspeel software ontvangt kijkt indien nodig naar het IP adres van de bezoeker om een secudaire GeoIP controle te doen.
+  * De streaming server welke het verzoek van de media afspeel software ontvangt kijkt indien nodig naar de anti-deeplink argumenten om een secundaire anti-deeplink controle te doen
+  * De streaming server serveert de stream uit aan de media afspeel software van de bezoeker.
+===== Nieuwe stream aanvragen =====
+De volgende informatie is van toepassing op windows media streams.
+Op het moment dat u door ons een livestream wilt onderbrengen dient u de volgende gegevens door te geven:
+  * Bron signaal van de stream, dat kan een publishing point op een relayserver zijn, of een IP adres plus poort van een encoder
+  * Het shared secret voor de anti deeplink beveiliging
+  * Of er GeoIP afscherming op de stream van toepassing is en zo ja, de landen welke wel of juist niet mogen kijken
+Vervolgens krijgt u van ons te horen wat het livestreams.omroep.nl request zal zijn welke u kunt gebruiken op uw website.
+===== Controles ======
+==== GeoIP Controle ====
+In het geval van GeoIP controle hoeft de web ontwikkelaar hier geen bijzondere dingen voor te doen.
+Op het moment dat een bezoeker de stream opvraagt zal op dat moment diens IP adres tegen de GeoIP database aangehouden worden om te controleren of de bezoeker het verzoek uit een land doet welke al dan niet is toegestaan.  Vervolgens zal er ofwel een asx verwant uitgeserveerd worden, of een melding dat de bezoeker het verzoek niet uit een land doet welke is toegestaan.
+==== Anti Deeplink Controle ====
+Op alle streams is anti-deeplink controle van toepassing zodat bezoekers welke de stream willen zien dat via een site moeten doen welke op de hoogte is van de details van deze bescherming.  Voor deze bescherming dient de webdeveloper van de site een aantal zaken te regelen.  De argumenten welke livestreams.omroep.nl verwacht zijn er 2, namelijk md5 checksum en unix timestamp in hexadecimaal formaat.
+Het request wat uiteindelijk op livestreams.omroep.nl terecht moet komen heeft een vooraf te bepalen timeout waarde binnen welke het linkje gegenereerd en gebruikt moet worden.  Als een valide request voorbij deze timeout op livestreams.omroep.nl gedaan wordt zal deze besluiten dat het te lang geleden is dat de md5 checksum berekend is en het request als invalide beschouwen!
+Er zijn 2 verschillende manieren welke u kunt gebruiken om deze argumenten door te geven, namelijk:
+  * manier 1: http://livestreams.omroep.nl/<uri>?md5=<md5 checksum>&t=<hex timestamp>
+  * manier 2: http://livestreams.omroep.nl/secure/<md5 checksum>/<hex timestamp>/<uri>
+Een voorbeeld van deze argumenten is:
+> md5=9d53338df54109989eb32a2b0c0af968
+> t=4b549701
+De md5 checksum wordt berekend over een string met daarin op deze volgorde de volgende componenten:
+  * Secret welke alleen bekend is bij NPO en de eigenaar van de stream/webdeveloper van de site welke de links moet maken.
+  * livestreams.omroep.nl request URI (request **ex**clusief http://livestreams.omroep.nl) welke de anti-deeplink protectie geniet.
+  * De hexadecimale presentatie van de unix timestamp waarop de md5 checksum berekend wordt (Dit is tevens het 't' argument)
+Een stuk voorbeeld php code om de argumenten te berekenen voor, bijvoorbeeld, http://livestreams.omroep.nl/npo/videostream-bb:
+<code php>
+<?php
+$secret = "heelgeheimsecret";
+$uri = "/npo/videostream-bb";
+$t_hex = sprintf("%08x", time());
+$lsapiserver = 'http://livestreams.omroep.nl';
+$token = md5($secret . $uri . $t_hex);
+$url_manier1 = sprintf("%s%s?md5=%s&t=%s", $lsapiserver, $uri, $token, $t_hex);
+$url_manier2 = sprintf("%s/secure/%s/%s%s", $lsapiserver, $token, $t_hex, $uri);
+echo "Manier 1: $url_manier1\n";
+echo "Manier 2: $url_manier2\n";
+?>
+</code>
+Het resultaat van deze code als als unix timestamp ''1263907192 (hexadecimaal: 4b55b178)'' wordt gebruikt is:
+<code>
+Manier 1: http://livestreams.omroep.nl/npo/videostream-bb?md5=ff3c8aed28a7774b90f6d80188ff317b&t=4b55b178
+Manier 2: http://livestreams.omroep.nl/secure/ff3c8aed28a7774b90f6d80188ff317b/4b55b178/npo/videostream-bb
+</code>
+De lighttpd module mod_secdownload gebruikt dezelfde logica.
+Documentatie daarvoor is te vinden op: ''http://trac.lighttpd.net/trac/wiki/Docs:ModSecDownload''