Farstream.Stream

g Farstream.Stream Farstream.Stream GObject.Object GObject.Object GObject.Object->Farstream.Stream

Subclasses:None

Methods

Inherited:GObject.Object (37)
Structs:GObject.ObjectClass (5)
  add_id (id)
  add_remote_candidates (candidates)
  destroy ()
  emit_error (error_no, error_msg)
  emit_src_pad_added (pad, codec)
  force_remote_candidates (remote_candidates)
  iterate_src_pads ()
  parse_component_state_changed (message)
  parse_local_candidates_prepared (message)
  parse_new_active_candidate_pair (message)
  parse_new_local_candidate (message)
  parse_recv_codecs_changed (message)
  set_decryption_parameters (parameters)
  set_remote_codecs (remote_codecs)
  set_transmitter (transmitter, stream_transmitter_parameters)
  set_transmitter_ht (transmitter, stream_transmitter_parameters)

Virtual Methods

Inherited:GObject.Object (7)
  do_add_id (id)
  do_add_remote_candidates (candidates)
  do_force_remote_candidates (remote_candidates)
  do_set_decryption_parameters (parameters)
  do_set_remote_codecs (remote_codecs)
  do_set_transmitter (transmitter, stream_transmitter_parameters)

Properties

Name Type Flags Short Description
current-recv-codecs   r A GLib.List of Farstream.Codec representing the codecs that have been received
decryption-parameters Gst.Structure r Parameters used to decrypt the stream
direction Farstream.StreamDirection r/w/c An enum to set and get the direction of the stream
negotiated-codecs   r A GLib.List of FsCodecs of the negotiated codecs for this stream
participant Farstream.Participant r/w/co An Farstream.Participant represented by the stream
remote-codecs   r A GLib.List of FsCodecs of the remote codecs
require-encryption bool r/w If True, only encrypted content will be accepted
session Farstream.Session r/w/co An Farstream.Session represented by the stream

Signals

Inherited:GObject.Object (1)
Name Short Description
error This signal is emitted in any error condition
src-pad-added This signal is emitted when a new gst source pad has been created for a specific codec being received.

Fields

Inherited:GObject.Object (1)
Name Type Access Description
parent GObject.Object r  

Class Details

class Farstream.Stream(**kwargs)
Bases:GObject.Object
Abstract:Yes
Structure:Farstream.StreamClass

All members are private, access them using methods and properties

add_id(id)
Parameters:id (int) – The id to add to the stream

This function is used to add data identifiers that allow the plugin to recognize packets that are meant for id. For example, in RTP, one would set the SSRCs that are expected.

Depending on the protocol, one may be able to add more than one ID to a stream (in RTP you can have multiple SSRCs in a stream). If a protocol supports only one id, adding a new one will overwrite it. If an ID was already set on a stream, adding it to another stream will override the previdous decision.

For most protocols, calling this function is optional as the incoming data can be matched with a stream by its source IP address. This is mostly useful if one is using multicast or is behind a muxer server.

add_remote_candidates(candidates)
Parameters:candidates ([Farstream.Candidate]) – an GLib.List of Farstream.Candidate representing the remote candidates
Raises:GLib.Error
Returns:True if the candidate was valid, False otherwise
Return type:bool

This function adds remote candidates. Any new candidates are added to the list. The candidates will be used to establish a connection with the peer. A copy will be made so the user must free the passed candidate using fs_candidate_destroy() when done.

destroy()

This will cause the stream to remove all links to other objects and to remove itself from the Farstream.Session. Once a Farstream.Stream has been destroyed, it can not be used anymore.

It is strongly recommended to call this function from the main thread because releasing the application’s reference to a stream.

emit_error(error_no, error_msg)
Parameters:
  • error_no (int) – The number of the error
  • error_msg (str) – Error message to be displayed to user

This function emits the Farstream.Stream ::error” signal, it should only be called by subclasses.

emit_src_pad_added(pad, codec)
Parameters:

Emits the Farstream.Stream ::src-pad-added” signal, it should only be called by subclasses.

force_remote_candidates(remote_candidates)
Parameters:remote_candidates ([Farstream.Candidate]) – a GLib.List of Farstream.Candidate to force
Raises:GLib.Error
Returns:True if the candidates could be forced, False otherwise
Return type:bool

This function forces data to be sent immediately to the selected remote candidate, by-passing any connectivity checks. There should be at most one candidate per component.

iterate_src_pads()
Returns:The Gst.Iterator
Return type:Gst.Iterator

Creates a Gst.Iterator that can be used to iterate the src pads of this stream. These are the pads that were announced by Farstream.Stream :src-pad-added and are still valid.

parse_component_state_changed(message)
Parameters:message (Gst.Message) – a Gst.Message to parse
Returns:True if the message matches the stream and is valid.
component:Returns the component from the Gst.Message if not None
state:Returns the Farstream.StreamState from the Gst.Message if not None
Return type:(bool, component: int, state: Farstream.StreamState)

Parses a “farstream-component-state-changed” message and checks if it matches the self parameters.

parse_local_candidates_prepared(message)
Parameters:message (Gst.Message) – a Gst.Message to parse
Returns:True if the message matches the stream and is valid.
Return type:bool

Parses a “farstream-local-candidates-prepared” message and checks if it matches the self parameters.

parse_new_active_candidate_pair(message)
Parameters:message (Gst.Message) – a Gst.Message to parse
Returns:True if the message matches the stream and is valid.
local_candidate:
 Returns the local Farstream.Candidate in the message if not None.
remote_candidate:
 Returns the remote Farstream.Candidate in the message if not None.
Return type:(bool, local_candidate: Farstream.Candidate, remote_candidate: Farstream.Candidate)

Parses a “farstream-new-active-candidate-pair” message and checks if it matches the self parameters.

parse_new_local_candidate(message)
Parameters:message (Gst.Message) – a Gst.Message to parse
Returns:True if the message matches the stream and is valid.
candidate:Returns the Farstream.Candidate in the message if not None.
Return type:(bool, candidate: Farstream.Candidate)

Parses a “farstream-new-local-candidate” message and checks if it matches the self parameters.

parse_recv_codecs_changed(message)
Parameters:message (Gst.Message) – a Gst.Message to parse
Returns:True if the message matches the stream and is valid.
codecs:Returns a GLib.List of Farstream.Codec of the message if not None
Return type:(bool, codecs: [Farstream.Codec])

Parses a “farstream-recv-codecs-changed” message and checks if it matches the self parameters.

set_decryption_parameters(parameters)
Parameters:parameters (Gst.Structure) – a Gst.Structure containing the decryption parameters
Raises:GLib.Error
Returns:True if the decryption parameters could be set, False otherwise
Return type:bool

Sets decryption parameters. The exact parameters depend on the type of plugin being used.

set_remote_codecs(remote_codecs)
Parameters:remote_codecs ([Farstream.Codec]) – a GLib.List of Farstream.Codec representing the remote codecs
Raises:GLib.Error
Returns:False if the remote codecs couldn’t be set.
Return type:bool

This function will set the list of remote codecs for this stream. If the given remote codecs couldn’t be negotiated with the list of local codecs or already negotiated codecs for the corresponding Farstream.Session, error will be set and False will be returned. The remote_codecs list will be copied so it must be free’d using fs_codec_list_destroy() when done.

set_transmitter(transmitter, stream_transmitter_parameters)
Parameters:
Raises:

GLib.Error

Returns:

True if the transmitter could be set, False otherwise

Return type:

bool

Set the transmitter to use for this stream. This function will only succeed once.

The parameters correspond to the varios GObject.Object properties of the selected stream transmitter.

set_transmitter_ht(transmitter, stream_transmitter_parameters)
Parameters:
  • transmitter (str) – Name of the type of transmitter to use for this stream
  • stream_transmitter_parameters ({str: GObject.Value} or None) – A GLib.HashTable of string->:obj:GObject.Value containing the parameters.
Raises:

GLib.Error

Returns:

True if the transmitter could be set, False otherwise

Return type:

bool

Set the transmitter to use for this stream. This function will only succeed once.

The parameters correspond to the varios GObject.Object properties of the selected stream transmitter.

This is the same as Farstream.Stream.set_transmitter() except that the parameters are passed in a GLib.HashTable to make it more friendly to GObject.Object introspection

do_add_id(id) virtual
Parameters:id (int) – The id to add to the stream

This function is used to add data identifiers that allow the plugin to recognize packets that are meant for id. For example, in RTP, one would set the SSRCs that are expected.

Depending on the protocol, one may be able to add more than one ID to a stream (in RTP you can have multiple SSRCs in a stream). If a protocol supports only one id, adding a new one will overwrite it. If an ID was already set on a stream, adding it to another stream will override the previdous decision.

For most protocols, calling this function is optional as the incoming data can be matched with a stream by its source IP address. This is mostly useful if one is using multicast or is behind a muxer server.

do_add_remote_candidates(candidates) virtual
Parameters:candidates ([Farstream.Candidate]) – an GLib.List of Farstream.Candidate representing the remote candidates
Returns:True if the candidate was valid, False otherwise
Return type:bool

This function adds remote candidates. Any new candidates are added to the list. The candidates will be used to establish a connection with the peer. A copy will be made so the user must free the passed candidate using fs_candidate_destroy() when done.

do_force_remote_candidates(remote_candidates) virtual
Parameters:remote_candidates ([Farstream.Candidate]) – a GLib.List of Farstream.Candidate to force
Returns:True if the candidates could be forced, False otherwise
Return type:bool

This function forces data to be sent immediately to the selected remote candidate, by-passing any connectivity checks. There should be at most one candidate per component.

do_set_decryption_parameters(parameters) virtual
Parameters:parameters (Gst.Structure) – a Gst.Structure containing the decryption parameters
Returns:True if the decryption parameters could be set, False otherwise
Return type:bool

Sets decryption parameters. The exact parameters depend on the type of plugin being used.

do_set_remote_codecs(remote_codecs) virtual
Parameters:remote_codecs ([Farstream.Codec]) – a GLib.List of Farstream.Codec representing the remote codecs
Returns:False if the remote codecs couldn’t be set.
Return type:bool

This function will set the list of remote codecs for this stream. If the given remote codecs couldn’t be negotiated with the list of local codecs or already negotiated codecs for the corresponding Farstream.Session, error will be set and False will be returned. The remote_codecs list will be copied so it must be free’d using fs_codec_list_destroy() when done.

do_set_transmitter(transmitter, stream_transmitter_parameters) virtual
Parameters:
Returns:

True if the transmitter could be set, False otherwise

Return type:

bool

Set the transmitter to use for this stream. This function will only succeed once.

The parameters correspond to the varios GObject.Object properties of the selected stream transmitter.

Signal Details

Farstream.Stream.signals.error(stream, errorno, error_msg)
Signal Name:

error

Flags:

RUN_LAST

Parameters:
  • stream (Farstream.Stream) – The object which received the signal
  • errorno (Farstream.Error) – The number of the error
  • error_msg (str) – Error message to be displayed to user

This signal is emitted in any error condition

Farstream.Stream.signals.src_pad_added(stream, pad, codec)
Signal Name:

src-pad-added

Flags:

RUN_LAST

Parameters:

This signal is emitted when a new gst source pad has been created for a specific codec being received. There will be a different source pad for each codec that is received. The user must ref the Gst.Pad if he wants to keep it. The user should not modify the Farstream.Codec and must copy it if he wants to use it outside the callback scope.

This signal is not emitted on the main thread, but on GStreamer’s streaming thread!

Property Details

Farstream.Stream.props.current_recv_codecs
Name:current-recv-codecs
Type:
Default Value:None
Flags:READABLE

This is the list of codecs that have been received by this stream. The user must free the list if fs_codec_list_destroy(). The “farstream-recv-codecs-changed” message is send on the Gst.Bus when the value of this property changes. It is normally emitted right after Farstream.Stream ::src-pad-added only if that codec was not previously received in this stream, but it can also be emitted if the pad already exists, but the source material that will come to it is different.

Farstream.Stream.props.decryption_parameters
Name:decryption-parameters
Type:Gst.Structure
Default Value:None
Flags:READABLE

Retrieves previously set decryption parameters

Farstream.Stream.props.direction
Name:direction
Type:Farstream.StreamDirection
Default Value:Farstream.StreamDirection.NONE
Flags:READABLE, WRITABLE, CONSTRUCT

The direction of the stream. This property is set initially as a parameter to the Farstream.Session.new_stream() function. It can be changed later if required by setting this property.

Farstream.Stream.props.negotiated_codecs
Name:negotiated-codecs
Type:
Default Value:None
Flags:READABLE

This is the list of negotiatied codecs, it is the same list as the list of Farstream.Codec from the parent Farstream.Session, except that the codec config data has been replaced with the data from the remote codecs for this stream. This is the list of Farstream.Codec used to receive data from this stream. It is a GLib.List of Farstream.Codec.

Farstream.Stream.props.participant
Name:participant
Type:Farstream.Participant
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

The Farstream.Participant for this stream. This property is a construct param and is read-only construction.

Farstream.Stream.props.remote_codecs
Name:remote-codecs
Type:
Default Value:None
Flags:READABLE

This is the list of remote codecs for this stream. They must be set by the user as soon as they are known using Farstream.Stream.set_remote_codecs() (generally through external signaling). It is a GLib.List of Farstream.Codec.

Farstream.Stream.props.require_encryption
Name:require-encryption
Type:bool
Default Value:False
Flags:READABLE, WRITABLE

If set to True, only encrypted content will be accepted on this stream.

Farstream.Stream.props.session
Name:session
Type:Farstream.Session
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

The Farstream.Session for this stream. This property is a construct param and is read-only construction.