.. _ref-media:
###########################
Maongo-Media
###########################
.. note:: XXXXXXXXXXXXXXX Überarbeitung 25.7.2011 XXXXXXXXXXXXXXXXXXXX
.. _ref-mediaplayer:
MediaPlayerWidget
===============================================================================
``maongo.core.toolkit.MediaPlayerWidget extends Widget``
Das MediaPlayerWidget dient der Wiedergabe von Audio und Video.
Ein einfaches MediaPlayerWidget::
Properties
------------
**AutoFallback** (Boolean)
Soll der Player automatisch nach Alternativen in den verfügbaren Quellen suchen, wenn keine Verbindung zustande kommt.
*NYI*
**AutoFallbackTime** (Number)
Zeit in Sekunden nach der Alternativ-Quellen ausprobiert werden.
*NYI*
**CurrentTime** (Time, readonly)
Liefert die momentane Zeitposition des wiedergegebenen Mediums.
**LoopCount** (Number)
Anzahl der abzuspielenden Loops für das Medium.
**MediaType** (Symbol)
Der Medientyp welcher wiedergegeben werden soll.
Default: ``video``
Werte: ``video``, ``audio``
**MetaData** (Map, readonly)
Liefert eine Map mit Metadaten zum aktuell wiedergegebenen Medium.
Hinweis::
Format und Inhalt des Objektes sind noch undefiniert
**PlaybackControl** (Symbol)
Hiermit wird der momentane Abspielzustand gesetzt. Im Default-Zustand wird hierdurch ein Autoplay ermöglicht.
Default: ``play``
Werte: ``play``, ``pause`` , ``stop``
::
**PosterFrame** (Image)
Ein Bild welches angezeigt wird, wenn das Medium noch nicht bzw. nicht angezeigt werden kann.
::
**Quality** (String)
Dient zur Ermittlung der Medienquelle aus einer evt. Liste mit mehreren Einträgen. Dabei muss der Eintrag in der Quelle
mit dem Wert dieser Eigenschaft übereinstimmen, damit die Quelle als passend betrachtet wird. In der Defaulteinstellung ``auto``
wird jede Quelle als passend betrachtet.
Default: ``auto``
**Source** (Media)
Angabe welche Medienquelle wiedergegeben werden soll.
Momentan unterstützte Formate und Protokolle:
Video:
MP4 Dateien über HTTP-Protokoll und RTMP-Streams
Audio:
MP3 Dateien über HTTP-Protokoll
Dabei kann entweder eine Quelle in der folgenden Syntax angegeben werden::
Diese versuchen die Player auf den Plattformen wiederzugeben.
Um verschiedene Quellen für unterschiedliche Plattformen oder
unterschiedliche Qualitäten einer Mediendatei anzugeben, ist es auch möglich eine Liste mit Quellen anzugeben. Diese wird
von den Playern nach passenden Quellen durchsucht. Sollte dabei keine mit allen Kriterien (Plattform, Wiedergabeformate, Qualität)
übereinstimmende Quelle gefunden werden, wird versucht eine für diese Plattform passende zu finden. Danach wird der erste Treffer aus
der Liste abgespielt.
Syntax für mehrere Quellen::
Zur Beschreibung des Mediums können die folgenden Einträge in der Map übergeben werden:
``URL`` (String)
Die Url von der das Medium wiedergegeben werden soll. Es können HTTP, RTMP oder RTMPT-Quellen angegeben werden.
Bei Angabe einer HTTP-Quelle ist die Angabe der Property ``MediaPath`` nicht notwendig. Für RTMP- bzw. RTMPT-Quellen
ist hier die URL des Media-Servers anzugeben. Die Angabe des wiederzugebenden Mediums erfolgt in der Property ``MediaPath``
.. note:: RTMP-Quellen werden derzeit nur in der Flash-Ausspielung unterstützt. Dabei wird eine Verbindung über RTMP und RTMPT aufgebaut und die schnellere Verbindung wird zur Wiedergabe genutzt.
``MediaPath`` (String)
Sofern RTMP/RTMPT-Quellen genutzt werden sollen, muss in dieser Property der für den Verbindungsaufbau notwendige Pfad zur
tatsächlichen Medienquelle angegeben werden.
``UseFCSubscribe`` (String)
Soll für die Verbindung mit einem Media-Server über RTMP/RTMPT ein Subscribe Aufruf geschickt werden?
Dies ist bei bestimmten Media-Servern notwendig um Medien abspielen zu können.
Default: ``true``
Values: ``true``, ``false``
``UsePolicyFile`` (String)
Nur unter Flash bei der Wiedergabe von HTTP-Videos relevant. Sofern die Property auf ``true`` gesetzt ist, wird für das Video
nach einem Cross-Domain-Policy File gesucht um zu prüfen, ob der Zugriff auf das Video erlaubt ist.
Default: ``true``
Values: ``true``, ``false``
``Protocol`` (String)
Diese Eigenschaft legt fest, welche Art von Verbindung aufgebaut wird. Dies ist nur auf Plattformen relevant, welche neben HTTP auch RTMP/T/S unterstützen.
Values: ``HTTP``, ``RTMP``, ``RTMPT``, ``RTMPS``
``Type`` (String)
Art der Medienquelle um den Playern auf den Plattformen zu ermöglichen passende Formate zu finden.
Values: ``video/mp4``, ``video/ogg``
``Platform`` (String)
Zielplattform für die diese Quelle gedacht ist.
Values: ``HTML``, ``Flash``, ``Java``
**TextureMode**
Mit der Eigenschaft "TextureMode" beeinflussen Sie die Art und Weise, mit der ein Medium in ein Widget eingepasst wird::
Der Standardwert der Eigenschaft TextureMode ist ``top-left``.
off
Das Medium wird nicht angezeigt. Audio wird trotzdem abgespielt.
Weitere Werte siehe :ref:`ref-texturemode`.
**TotalTime** (Time, readonly)
Liefert die Gesamtlänge des wiedergegebenen Mediums. Sofern die Gesamtlänge des wiedergegebenen Mediums nicht bekannt ist, liefert diese Eigenschaft ``-1`` zurück.
**VideoSize** (RectangleXP, readonly)
Liefert die "echte" Größe des Videos zurück, unabhängig von evtl. Skalierung. Sofern die Größe des Videos nicht bekannt ist, liefert diese Eigenschaft ``null``.
**Volume** (Number)
Lautstärke des wiedergegebenen Mediums. Sofern die Tonwiedergabe eines Mediums "getogglet" wird, ändert sich das Volume nicht.
Default: ``1.0``
Werte: ``0.0`` bis ``1.0``
Methoden
------------
**play()**
Spielt das Medium ab bzw. startet die Wiedergabe nach einer Pause wieder.
**pause()**
Pausiert die Wiedergabe des Mediums.
**rewind()**
Spult das Medium an die Anfangsposition zurück. Dies entspricht einem ``seek(0)``.
.. note:: Derzeit in Java nicht implementiert.
**seek(targetposition)**
Springt an die in ``targetposition`` angegebene Zeitposition und verhält sich danach genauso wie vorher.
Ein laufendes Medium wird nach einem ``seek(10)`` also weiterhin abgespielt, ein pausiertes Medium wird an der neuen Position pausiert. Angabe in Sekunden.
.. note:: Derzeit in Java nicht implementiert.
**stop()**
Stoppt die Wiedergabe des Mediums. Das Medium beginnt nach einem folgenden ``play()`` wieder am Anfang. Durch den Aufruf von ``stop()`` wird der Buffer geleert
und evt. die Verbindung zu einem Server getrennt. Es kann also nach einem erneuten ``play()`` etwas dauern bis die Wiedergabe erneut beginnt. Wenn ein "Soft-Stop" ausgeführt werden soll,
ist dieser mit ``pause(); seek(0);`` zu erreichen.
**toggleMute()**
Wechselt zwischen abgeschaltetem und angeschaltetem Ton. Dabei wird das Volume des Mediums nicht verändert. Nach dem Wiederanschalten ist der Ton also genauso laut wie vor dem Abschalten.
Signale
------------
Signale sind weitgehend identisch auf allen Plattformen implementiert. Es kann allerdings zu unterschiedlichen Zeitpunkte oder Reihenfolgen beim Aussenden der Signale
kommen, da die einzelnen Plattformen mit Medien sehr unterschiedlich umgehen.
**media-buffer**
Der Buffering-Vorgang für ein Medium hat begonnen.
.. note:: Derzeit in Java nicht implementiert.
**media-error**
Beim Laden oder Wiedergeben eines Mediums ist ein Fehler aufgetreten
**media-finish**
Die Wiedergabe eines Mediums ist beendet.
**media-pause**
Die Wiedergabe des Mediums wurde pausiert. Bei erneuter Wiedergabe erfolgt die Wiedergabe ab der momentanen Abspielposition.
**media-play**
Die Wiedergabe eines Mediums hat begonnen. Dieses Signal wird entweder bei Wiedergabe nach einem Stop, nach einer Pause oder bei erstmaliger Wiedergabe des Videos ausgesendet.
**media-seek**
Eine Änderung der Abspielposition wurde angestossen. Sobald die neue Abspielposition erreicht ist, verhält sich das Video wie vorher, wird also pausiert oder abgespielt.
**media-stop**
Die Wiedergabe des Mediums wurde gestoppt. Sofern das Medium wieder abgespielt wird, erfolgt die Wiedergabe vom Anfang an.
In der HTML-Ausspielung erhält man aufgrund von Plattformspezifika nach einem ``media-stop`` noch eine ``media-seek`` Signal.
**media-status**
Dieses Signal wird bei jeder Statusänderung des Mediums ausgesendet und beinhaltet den neuen Status des Mediums.
Values: ``buffer``, ``error``, ``finish``, ``pause``, ``play``, ``seek``, ``stop``
Beispiel
------------
::