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:

pad (Gst.Pad) – the Gst.Pad that this Farstream.Stream has created
codec (Farstream.Codec) – The Farstream.Codec for this pad

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:

transmitter (str) – Name of the type of transmitter to use for this stream
stream_transmitter_parameters ([GObject.Parameter] or None) – an array of n_parameters GObject.Parameter struct that will be passed to the newly-create Farstream.StreamTransmitter

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:

transmitter (str) – Name of the type of transmitter to use for this stream
stream_transmitter_parameters ([GObject.Parameter] or None) – an array of n_parameters GObject.Parameter struct that will be passed to the newly-create Farstream.StreamTransmitter

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:

stream (Farstream.Stream) – The object which received the signal
pad (Gst.Pad) – Gst.Pad of the new source pad
codec (Farstream.Codec) – Farstream.Codec of the codec being received on the new source pad

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.