# Default Nodes Scripts

These scripts contain logic to select default source and sink nodes and also manage user preferences regarding those.

## Hooks

Management of the default source and sink nodes is implemented by scanning all the available nodes in the graph and assigning them a priority based on certain logic. The node with the highest priority in each category becomes the default.

Scanning is implemented using a "rescan-for-default-nodes" event. The "default-nodes/rescan-trigger" hook is the one that monitors graph changes and schedules "rescan-for-default-nodes". Then, the "default-nodes/rescan" hook is executed for the "rescan-for-default-nodes" event and it pushes a "select-default-node" event for each one of the categories where a default node is required:

> - Audio sink

> - Audio source

> - Video source

Hooks triggered by changes in the graph
Hook name | File | Triggered by | Action
--- | --- | --- | ---
default-nodes/rescan-trigger | rescan.lua | linkables added/removed or default.configured.* metadata changed | schedule rescan-for-default-nodes
default-nodes/store-configured-default-nodes | state-default-nodes.lua | default.configured.* metadata changed | stores user selections in the state file
default-nodes/metadata-added | state-default-nodes.lua | metadata object created | restores default.configured.* values from the state file

Hooks for the rescan-for-default-nodes event, in order of execution
Hook name | File | Description
--- | --- | ---
m-standard-event-source/rescan-done | module-standard-event-source.c | clears the rescan_scheduled flag
default-nodes/rescan | rescan.lua | schedules select-default-node for each category

Hooks for the select-default-node event, in order of execution
Hook name | File | Description
--- | --- | ---
default-nodes/find-selected-default-node | find-selected-default-node.lua | prioritizes the current default.configured.* node, i.e. the current user selection
default-nodes/find-stored-default-node | state-default-nodes.lua | prioritizes past user selections from the state file
default-nodes/find-best-default-node | find-best-default-node.lua | prioritizes nodes based on their priority.session property & their associated Route priority
default-nodes/apply-default-node | apply-default-node.lua | sets the highest priority selected node as the default in the metadata

## select-default-node event

High priority event to select the default node for a given category (media.type & direction combination).

In this event, each hook is tasked to find the highest priority node of the category it runs for. In order to do that, a list of available nodes is calculated in advance, by the "default-nodes/rescan" hook, and passed on to each of the "select-default-node" hooks via event data. Each hook then has to go through this list and select a node, placing it in the "selected-node" event data together with its priority number in "selected-node-priority". The next hook, then, may override the "selected-node" and "selected-node-priority" with something else, but only if the new priority is higher than the old one.

Event properties
Property name | Description
--- | ---
default-node.type | the suffix of the metadata keys related to this default node (audio.sink, audio.source or video.source)

Exchanged event data
Name | Description
--- | ---
available-nodes | JSON array of all selectable nodes, with each element containing all node properties
selected-node | the selected node's node.name (string)
selected-node-priority | the priority (integer)