Skip to main content

Hooks

How a stream decides​

For each person and each stream, Live Stream decides in this order:

  1. Hosts: administrators host every stream, the user a stream is the stream of hosts it (its host), and those wordplus_stream_can_host adds. A host goes live, moderates and writes in the chat, and is asked nothing more.
  2. Viewers: the Who can watch setting of the stream, then wordplus_stream_can_watch.
  3. The chat: logged-in viewers write in the light chat, and visitors where the stream lets them. wordplus_stream_can_chat has the last word.
  4. Moderators: those who moderate the comments of the site and the roles chosen in the stream, then wordplus_stream_can_moderate.

What it decides goes into the grant each person joins with, which WordPlus Cloud holds them to. A page a cache keeps carries the grant of a visitor for a public stream, so a filter that keeps visitors out takes effect on the pages made after it.

Filters are asked often, on each page that shows a stream and for each stream of the Live now list. Keep them quick: wordplus_streams()->get_object() reads what a stream was made for without the rest of it.

Filters​

wordplus_stream_can_host​

Whether a logged-in user hosts a stream. Not asked for administrators, who host every stream.

apply_filters( 'wordplus_stream_can_host', bool $can, int $stream_id, int $user_id )

$can is false. A host goes live from the studio of the stream where your page shows it (wordplus_streams()->render() with 'part' => 'studio'), or from the studio wordplus_stream_studio_url links them to. Live Stream → Studio in the admin stays for administrators.

// The organisers of a group host its stream.
add_filter( 'wordplus_stream_can_host', function ( $can, $stream_id, $user_id ) {
	$group = wordplus_streams()->get_object( $stream_id );

	if ( $group && 'my_group' === $group['type'] ) {
		return my_group_is_organiser( $group['id'], $user_id );
	}

	return $can;
}, 10, 3 );

wordplus_stream_can_watch​

Whether a user may watch a stream: how membership plugins make a stream paid or for members. Not asked for its hosts.

apply_filters( 'wordplus_stream_can_watch', bool $can, array $rules, int $user_id, int $stream_id )

$can is true, the answer of the Who can watch setting, which already kept out those it does not let in. $rules are those of the stream (s, its ID on the cloud, t its title, a its access). $user_id is 0 for a visitor. Someone kept out sees You do not have access to this stream in the player.

// Only the members of the group watch its stream.
add_filter( 'wordplus_stream_can_watch', function ( $can, $rules, $user_id, $stream_id ) {
	$group = wordplus_streams()->get_object( $stream_id );

	if ( $group && 'my_group' === $group['type'] ) {
		return $can && my_group_is_member( $group['id'], $user_id );
	}

	return $can;
}, 10, 4 );

wordplus_stream_can_chat​

Whether a viewer writes in the light chat of a stream, or only reads it. Not asked for its hosts, who always write, nor for a stream whose chat is a Better Messages chat room, which decides that itself.

apply_filters( 'wordplus_stream_can_chat', bool $can, int $stream_id, int $user_id )

$can says what the stream lets them: logged-in users write, and visitors where Visitors may write is on. Returning true for a visitor lets them write too, as "Guest".

wordplus_stream_can_moderate​

Whether a logged-in viewer moderates a stream: pins and deletes messages, mutes, removes and bans people, turns on slow mode. Not asked for its hosts, who always moderate, nor for visitors.

apply_filters( 'wordplus_stream_can_moderate', bool $can, int $stream_id, int $user_id )

$can is true for those who moderate the comments of the site and for the roles chosen in the stream.

wordplus_stream_studio_url​

Where the player sends a host to go live.

apply_filters( 'wordplus_stream_studio_url', string $url, int $stream_id, int $user_id )

$url is Live Stream → Studio for administrators, and '' for the hosts your plugin names, who may not open the admin. With '', the stream in one piece carries the studio for them. Send them to the page where you put the studio:

add_filter( 'wordplus_stream_studio_url', function ( $url, $stream_id, $user_id ) {
	$group = wordplus_streams()->get_object( $stream_id );

	return $group && 'my_group' === $group['type'] ? my_group_url( $group['id'] ) . 'live/' : $url;
}, 10, 3 );

wordplus_stream_page_url​

Where a stream is watched: the page the Live now list links to, which the player shares and puts in calendars from wherever it is shown, as in a feed.

apply_filters( 'wordplus_stream_page_url', string $url, int $stream_id )

$url is the page chosen in the settings of the stream, or the first public page found showing it, '' for none. A stream with no page is left out of the Live now list. wordplus_streams()->get() asks this filter for its page, so read the stream here with wordplus_streams()->get_host() or wordplus_streams()->get_object().

// The stream of a member is watched on their profile.
add_filter( 'wordplus_stream_page_url', function ( $url, $stream_id ) {
	$member = wordplus_streams()->get_host( $stream_id );

	return $member ? my_profile_url( $member ) : $url;
}, 10, 2 );

wordplus_stream_can_create​

Whether a logged-in user makes a stream of their own from the browser (wordplusStreams.create()), which they then host.

apply_filters( 'wordplus_stream_can_create', bool $can, int $user_id, array $args )

$can is true for administrators only. $args are title, settings, object_type and object_id, as the browser sent them: check that what it names is theirs, a group they organise, say.

// Every member makes streams of their own, for nothing of yours.
add_filter( 'wordplus_stream_can_create', function ( $can, $user_id, $args ) {
	return $can || empty( $args['object_type'] );
}, 10, 3 );

wordplus_stream_user_settings​

The settings a user gives a stream of their own from the browser, before they are checked. They send only access, watch_roles, chat, guest_chat, chat_offline, chat_links, chat_fresh, people, reactions, sessions, scheduled, cover and texts: the Better Messages chat room, the roles that moderate and the page of the Live now list are the site to choose.

apply_filters( 'wordplus_stream_user_settings', array $settings, int $user_id, int $stream_id )

$stream_id is 0 for a stream being made. Return the settings to keep:

// The streams of members are for logged-in users, whatever they choose.
add_filter( 'wordplus_stream_user_settings', function ( $settings ) {
	return array( 'access' => 'logged_in' ) + $settings;
} );

wordplus_stream_can_edit​

Whether a user changes and deletes a stream from the browser (wordplusStreams.update(), wordplusStreams.delete()).

apply_filters( 'wordplus_stream_can_edit', bool $can, int $stream_id, int $user_id )

$can is true for the user it is the stream of, and for administrators.

wordplus_stream_grant_claims​

The claims of the grant a person joins with, after everything above. To change the name or the avatar shown in the chat, add the origins of pages on other domains that show the stream to org, or shorten ttl. Return anything but an array to refuse the grant.

apply_filters( 'wordplus_stream_grant_claims', array $claims, array $rules, int $user_id )

wordplus_stream_track_watch​

Whether the site hears of the watch of a signed-in person, in wordplus_stream_joined and wordplus_stream_left. Asked as they join a stream, and only while anything listens to either action.

apply_filters( 'wordplus_stream_track_watch', bool $track, int $stream_id, int $user_id )
// Only the streams of members, not those the site runs.
add_filter( 'wordplus_stream_track_watch', function ( $track, $stream_id ) {
	return $track && wordplus_streams()->get_host( $stream_id ) > 0;
}, 10, 2 );

Actions​

wordplus_stream_live​

A stream went live: for a post in a feed as a member goes live, or a notice to their followers.

do_action( 'wordplus_stream_live', int $stream_id, array $stream, array $times )

$stream is as wordplus_streams()->get() gives it, and $times holds started, when it went live (a timestamp).

add_action( 'wordplus_stream_live', function ( $stream_id, $stream ) {
	if ( $stream['host'] ) {
		my_notify_followers( $stream['host'], $stream['title'], $stream['page'] );
	}
}, 10, 2 );

wordplus_stream_ended​

A stream ended, after wordplus_stream_live told it went live.

do_action( 'wordplus_stream_ended', int $stream_id, array $stream, array $times )

$times holds started and ended (timestamps), seconds on air, and who watched while it was live:

  • peak: the most people watching at once.
  • viewer_seconds: the seconds they all watched, added up. Divide by 60 for viewer minutes, or by seconds for how many watched on average.

The hosts and the guests on stage are not counted in either. Both are null when the site heard of the end by asking the cloud, as below.

// A live stream post keeps how many watched each time it was on air.
add_action( 'wordplus_stream_ended', function ( $stream_id, $stream, $times ) {
	if ( 'post' === $stream['object_type'] && null !== $times['peak'] ) {
		add_post_meta( $stream['object_id'], 'my_stream_audience', array(
			'ended'   => $times['ended'],
			'peak'    => $times['peak'],
			'minutes' => round( $times['viewer_seconds'] / 60 ),
		) );
	}
}, 10, 3 );

When they come: WordPlus Cloud tells the site the moment a stream goes live or ends, at the webhook of the site, and these come within a second. Where the cloud cannot reach the site, on a private network or behind a firewall, the site asks the cloud every minute while anything listens to them, and they come within a minute. Each comes once for each time a stream is on air, whichever way it was heard. A stream that was live for less than a minute on a site the cloud cannot reach may not be told at all.

wordplus_stream_joined​

Someone signed in started watching a live stream: they opened it while it was live, or it went live with them on its page. Also its hosts and the guests on stage, as they present it.

do_action( 'wordplus_stream_joined', int $stream_id, int $user_id, array $watch )

$watch holds role (viewer, host or guest), watch, an id for this watch that its wordplus_stream_left has too, and joined (a timestamp).

wordplus_stream_left​

Someone signed in stopped watching a live stream: they left, or it ended.

do_action( 'wordplus_stream_left', int $stream_id, int $user_id, array $watch )

$watch holds what wordplus_stream_joined had, plus left (a timestamp) and seconds watched. Only the time the stream was live counts: waiting on its page for it to start counts nothing, and a stream that goes live again starts another watch.

// How long each member watched, added up, for a badge or a report.
add_action( 'wordplus_stream_left', function ( $stream_id, $user_id, $watch ) {
	if ( 'viewer' === $watch['role'] ) {
		$total = (int) get_user_meta( $user_id, 'my_watched_seconds', true );
		update_user_meta( $user_id, 'my_watched_seconds', $total + $watch['seconds'] );
	}
}, 10, 3 );

Who is told of: only people signed in on the site. Visitors are counted in peak and viewer_seconds but never told of one by one. While anything listens to either action, the grants of signed-in people ask WordPlus Cloud to tell the site of their watches, and wordplus_stream_track_watch narrows that down. Nobody else costs the site a request.

When they come: within a second, at the webhook of the site, each once. A site the cloud cannot reach hears none of them.

wordplus_stream_created​

A stream was made: by an administrator, in a Better Messages chat room, or by your code.

do_action( 'wordplus_stream_created', int $stream_id, array $stream )

$stream is as wordplus_streams()->get() gives it.

wordplus_stream_updated​

The title or the settings of a stream were saved.

do_action( 'wordplus_stream_updated', int $stream_id, array $stream, array $before )

wordplus_stream_deleted​

A stream was deleted, by an administrator or by your code. Forget what you keep of it.

do_action( 'wordplus_stream_deleted', int $stream_id, array $stream )

$stream is as it was.

In the browser, a page hears the same as it happens: the stream it shows (wordplusStreams.on) and the streams of the site (wordplusStreams.live), in JavaScript.

Last updated on