Debian Codegraph @

src/scripts/default-nodes/README.rst

raw
1 Default Nodes Scripts
2 =====================
3
4 These scripts contain logic to select default source and sink nodes and also
5 manage user preferences regarding those.
6
7 Hooks
8 -----
9
10 Management of the default source and sink nodes is implemented by scanning all
11 the available nodes in the graph and assigning them a priority based on certain
12 logic. The node with the highest priority in each category becomes the default.
13
14 Scanning is implemented using a "rescan-for-default-nodes" event.
15 The "default-nodes/rescan-trigger" hook is the one that monitors graph changes
16 and schedules "rescan-for-default-nodes". Then, the "default-nodes/rescan"
17 hook is executed for the "rescan-for-default-nodes" event and it pushes a
18 "select-default-node" event for each one of the categories where a default node
19 is required:
20
21 - Audio sink
22 - Audio source
23 - Video source
24
25 .. list-table:: Hooks triggered by changes in the graph
26 :header-rows: 1
27 :width: 100%
28 :widths: 25 15 30 30
29
30 * - Hook name
31 - File
32 - Triggered by
33 - Action
34
35 * - default-nodes/rescan-trigger
36 - rescan.lua
37 - linkables added/removed or default.configured.* metadata changed
38 - schedule rescan-for-default-nodes
39
40 * - default-nodes/store-configured-default-nodes
41 - state-default-nodes.lua
42 - default.configured.* metadata changed
43 - stores user selections in the state file
44
45 * - default-nodes/metadata-added
46 - state-default-nodes.lua
47 - metadata object created
48 - restores default.configured.* values from the state file
49
50 .. list-table:: Hooks for the rescan-for-default-nodes event, in order of execution
51 :header-rows: 1
52 :width: 100%
53 :widths: 25 25 50
54
55 * - Hook name
56 - File
57 - Description
58
59 * - m-standard-event-source/rescan-done
60 - module-standard-event-source.c
61 - clears the rescan_scheduled flag
62
63 * - default-nodes/rescan
64 - rescan.lua
65 - schedules select-default-node for each category
66
67 .. list-table:: Hooks for the select-default-node event, in order of execution
68 :header-rows: 1
69 :width: 100%
70 :widths: 25 25 50
71
72 * - Hook name
73 - File
74 - Description
75
76 * - default-nodes/find-selected-default-node
77 - find-selected-default-node.lua
78 - prioritizes the current default.configured.* node, i.e. the current user selection
79
80 * - default-nodes/find-stored-default-node
81 - state-default-nodes.lua
82 - prioritizes past user selections from the state file
83
84 * - default-nodes/find-best-default-node
85 - find-best-default-node.lua
86 - prioritizes nodes based on their priority.session property & their associated Route priority
87
88 * - default-nodes/apply-default-node
89 - apply-default-node.lua
90 - sets the highest priority selected node as the default in the metadata
91
92 select-default-node event
93 -------------------------
94
95 High priority event to select the default node for a given category
96 (media.type & direction combination).
97
98 In this event, each hook is tasked to find the highest priority node of the
99 category it runs for. In order to do that, a list of available nodes is
100 calculated in advance, by the "default-nodes/rescan" hook, and passed on to
101 each of the "select-default-node" hooks via event data. Each hook then has
102 to go through this list and select a node, placing it in the "selected-node"
103 event data together with its priority number in "selected-node-priority".
104 The next hook, then, may override the "selected-node" and "selected-node-priority"
105 with something else, but only if the new priority is higher than the old one.
106
107 .. list-table:: Event properties
108 :header-rows: 1
109
110 * - Property name
111 - Description
112
113 * - default-node.type
114 - the suffix of the metadata keys related to this default node (audio.sink, audio.source or video.source)
115
116 .. list-table:: Exchanged event data
117 :header-rows: 1
118
119 * - Name
120 - Description
121
122 * - available-nodes
123 - JSON array of all selectable nodes, with each element containing all node properties
124
125 * - selected-node
126 - the selected node's node.name (string)
127
128 * - selected-node-priority
129 - the priority (integer)