python-librtmp 0.3.0
Python bindings for librtmp, built with cffi
License: Simplified BSD
Keywords: python-librtmp

python-librtmp
==============

.. image:: http://img.shields.io/pypi/v/python-librtmp.svg?style=flat-square
    :target: https://pypi.python.org/pypi/python-librtmp

.. image:: http://img.shields.io/pypi/dm/python-librtmp.svg?style=flat-square
    :target: https://pypi.python.org/pypi/python-librtmp

.. image:: http://img.shields.io/travis/chrippa/python-librtmp.svg?style=flat-square
    :target: http://travis-ci.org/chrippa/python-librtmp


python-librtmp is a `RTMP`_ client library. It uses the implementation
provided by `librtmp`_ via `cffi`_.

* Free software: `BSD license`_
* Documentation: http://pythonhosted.org/python-librtmp


.. _RTMP: http://en.wikipedia.org/wiki/Real_Time_Messaging_Protocol
.. _cffi: http://cffi.readthedocs.org/
.. _librtmp: http://rtmpdump.mplayerhq.hu/librtmp.3.html
.. _BSD license: http://opensource.org/licenses/BSD-2-Clause


Installation
============

The latest stable version is available to install using `pip`_

.. code-block:: console

    sudo pip install python-librtmp

But you can also get the development version using `Git <http://git-scm.com/>`_:

.. code-block:: console

    git clone git://github.com/chrippa/python-librtmp.git
    cd python-librtmp
    sudo python setup.py install


.. _pip: http://pip-installer.org/
.. _git: http://git-scm.com/


Dependencies
------------

- `Python`_, at least version 2.6 or 3.3.
- a C compiler capapable of building `Python`_ extensions, e.g. `gcc`_
- `librtmp`_: The library including its headers (`librtmp-dev` or equivalent)
- `cffi`_: cffi depends on libffi and its headers (`libffi-dev` or equivalent)
- On Python <3.4 the backport of `singledispatch`_ is also required.

.. _gcc: https://gcc.gnu.org/
.. _python: http://python.org/
.. _singledispatch: https://pypi.python.org/pypi/singledispatch


Windows
-------

python-librtmp (and `cffi`_) has wheel packages (binaries) available on PyPi and can
therefore be easily installed with `pip 1.4+ <http://www.pip-installer.org/>`_
without the need to compile anything:

.. code-block:: console

    > pip install python-librtmp

    (on older pip versions you need to use --use-wheel)
    > pip install --use-wheel python-librtmp


Features
========

Streaming
---------

The most common use case of RTMP is to read a video stream from
a server.

.. code-block:: python

    import librtmp

    # Create a connection
    conn = librtmp.RTMP("rtmp://your.server.net/app/playpath", live=True)
    # Attempt to connect
    conn.connect()
    # Get a file-like object to access to the stream
    stream = conn.create_stream()
    # Read 1024 bytes of data
    data = stream.read(1024)


Remote function calls
---------------------

Here is a example of creating a Python function that can be used to call
remote functions:

.. code-block:: python

    my_remote_method = conn.remote_method("MyRemoteMethod", block=True)
    result = my_remote_method("some argument")

Waiting for the server to call our function:

.. code-block:: python

    # This will automatically name the function after it's Python name
    @conn.invoke_handler
    def my_add(a, b):
        return a + b

    # Start waiting for calls
    conn.process_packets()

You can also use custom function name instead:

.. code-block:: python

    @conn.invoke_handler("MyMath.MyAdd")

Instead of blocking forever when waiting for a call you can specify to wait
only for a specific invoke and then stop blocking:

.. code-block:: python

    conn.process_packets(invoked_method="MyMath.MyAdd", timeout=30)






History
-------

0.3.0 (2015-05-25)
^^^^^^^^^^^^^^^^^^

* Added update_buffer option (enabled by default) to RTMP.create_stream,
  which enables a hack to increase throughput.
* Added a update_buffer method to RTMPStream.
* We now require at least version 1.0.1 of cffi.


0.2.2 (2015-04-15)
^^^^^^^^^^^^^^^^^^

* Fixed proxy not being used by librtmp.
* Added support for Cygwin, patch by @schrobby. (#17)


0.2.1 (2014-09-01)
^^^^^^^^^^^^^^^^^^

* Fixed expected bytes type on Python 2.
* Fixed singledispatch dependency condition.


0.2.0 (2014-04-07)
^^^^^^^^^^^^^^^^^^

* RTMPError now inherits from IOError.
* Fixed MSVC build.
* Added librtmp.so.1 to library paths, patch by Athanasios Oikonomou. (#4)
* Added librtmp.dylib to library paths, patch by Will Donohoe. (#6)


0.1.2 (2013-10-08)
^^^^^^^^^^^^^^^^^^

* Fixed compilation issue on some platforms.
* Fixed AMF issue on older librtmp versions. (#1)


0.1.1 (2013-09-25)
^^^^^^^^^^^^^^^^^^

* Fixed packaging issues.


0.1.0 (2013-09-23)
^^^^^^^^^^^^^^^^^^

* First release on PyPI.