diff --git a/docs/Tools.md b/docs/Tools.md index 7564f4fb..a1529cf8 100644 --- a/docs/Tools.md +++ b/docs/Tools.md @@ -98,17 +98,20 @@ watch -n 1 -p ./mxl-info mxl:///dev/shm/mxl?id=5fbec3b1-1b0f-417d-9059-8b94a4719 A binary that uses the gstreamer 'videotestsrc' and 'audiotestsrc' elements to produce video grains and/or audio samples which will be pushed to a MXL Flow. The flow is configured from a NMOS Flow json file. Here's an example of such file : +  **Note** Don't forget to provide valid description, label and grouphint tag. + + ```json { - "description": "MXL Test Flow, 1080p29", + "description": "___CHANGE ME___ Long description of the video flow", "id": "5fbec3b1-1b0f-417d-9059-8b94a47197ed", "tags": { "urn:x-nmos:tag:grouphint/v1.0": [ - "My Media Function Unique Name (Change Me):Video" + "___CHANGE ME FOR A NAME UNIQUE TO YOUR MEDIA FUNCTION INSTANCE___:Video" ] }, "format": "urn:x-nmos:format:video", - "label": "MXL Test Flow, 1080p29", + "label": "___CHANGE ME___ Short description of the video flow", "parents": [], "media_type": "video/v210", "grain_rate": { @@ -142,18 +145,21 @@ A binary that uses the gstreamer 'videotestsrc' and 'audiotestsrc' elements to p } ``` Below is an example of an **augmented NMOS Flow JSON** for audio. -  **Note:** The *channel_count* property is a mandatory MXL requirement (not found in standard NMOS definition). To adjust the number of audio channels, simply update the *channel_count* value. +  **Note 1:** The *channel_count* property is a mandatory MXL requirement (not found in standard NMOS definition). To adjust the number of audio channels, simply update the *channel_count* value. + +  **Note 2:** Don't forget to provide valid description, label and grouphint tag. + ```json { - "description": "MXL Audio Flow", + "description": "___CHANGE ME___ Long description of the audio flow", "format": "urn:x-nmos:format:audio", "tags": { "urn:x-nmos:tag:grouphint/v1.0": [ - "My Media Function Unique Name (Change Me):Audio" + "___CHANGE ME FOR A NAME UNIQUE TO YOUR MEDIA FUNCTION INSTANCE___:Audio #1" ] }, - "label": "MXL Audio Flow", + "label": "___CHANGE ME___ Short description of the audio flow", "version": "1441812152:154331951", "id": "b3bb5be7-9fe9-4324-a5bb-4c70e1084449", "media_type": "audio/float32", diff --git a/lib/include/mxl/flow.h b/lib/include/mxl/flow.h index b5f3ca78..4537aa2d 100644 --- a/lib/include/mxl/flow.h +++ b/lib/include/mxl/flow.h @@ -153,10 +153,43 @@ extern "C" typedef struct mxlFlowSynchronizationGroup_t* mxlFlowSynchronizationGroup; /** - * Attempt to create a flow writer for a given flow definition. If the flow does not exist already, it is created and 'created' will be set to + * Attempts to create a flow writer for a given flow definition. If the flow does not exist already, it is created and 'created' will be set to * true. If the flow exists, it will be opened and 'created' will be set to false. If the flow exists already it is not guaranteed that the flow * definition of the existing flow is exactly equal to the flow definition supplied in flowDef. The definition of the existing flow can be * retrieved using mxlGetFlowDef(). + * + * IMPORTANT NOTE
+ * The flow definition (flowDef) is expected to have well defined fields such as label, + * description and grouphint tag. This is a responsibility of the media function implementer. These fields should refer to the media function instance name. For example, on a large system with + * mutliple software defined decoders running simultaneously, each decoder instance should use a unique name in the grouphint tag to identify + * itself. Please read carefully the 'natural groups' section of the group hint tag specification. + * + * Example fields for an hypothetical video decoder media function instance named "Decoder 1": + * + * + * Example fields for a multi-flow audio receiver media function instance named "Audio Receiver A": + * Flow 1: + * + * + * Flow 2: + * + * + * Having a well formed grouphint tag refering to the media function instance name is essential to ensure proper flow discovery and + * management by higher level applications using MXL. + * * \param[in] instance The mxl instance created using mxlCreateInstance * \param[in] flowDef The flow definition from which a flow should be created if there is not already a flow with the same flow id. * \param[in] options (optional) Additional options, can be NULL diff --git a/lib/tests/data/audio_flow.json b/lib/tests/data/audio_flow.json index 4cc83c8f..2f63e780 100644 --- a/lib/tests/data/audio_flow.json +++ b/lib/tests/data/audio_flow.json @@ -1,14 +1,14 @@ { "$copyright": "SPDX-FileCopyrightText: 2025 Contributors to the Media eXchange Layer project.", "$license": "SPDX-License-Identifier: Apache-2.0", - "description": "MXL Audio Flow", + "description": "___CHANGE ME___ Long description of the audio flow", "format": "urn:x-nmos:format:audio", "tags": { "urn:x-nmos:tag:grouphint/v1.0": [ - "Media Function XYZ:Audio" + "___CHANGE ME FOR A NAME UNIQUE TO YOUR MEDIA FUNCTION INSTANCE___:Audio" ] }, - "label": "MXL Audio Flow", + "label": "___CHANGE ME___ Short description of the audio flow", "version": "1441812152:154331951", "id": "b3bb5be7-9fe9-4324-a5bb-4c70e1084449", "media_type": "audio/float32", @@ -20,4 +20,4 @@ "parents": [], "source_id": "2aa143ac-0ab7-4d75-bc32-5c00c13d186f", "device_id": "169feb2c-3fae-42a5-ae2e-f6f8cbce29cf" -} +} \ No newline at end of file diff --git a/lib/tests/data/data_flow.json b/lib/tests/data/data_flow.json index 4b7afc21..1828d151 100644 --- a/lib/tests/data/data_flow.json +++ b/lib/tests/data/data_flow.json @@ -1,14 +1,14 @@ { "$copyright": "SPDX-FileCopyrightText: 2025 Contributors to the Media eXchange Layer project.", "$license": "SPDX-License-Identifier: Apache-2.0", - "description": "MXL VANC Data", + "description": "___CHANGE ME___ Long description of the data flow", "tags": { "urn:x-nmos:tag:grouphint/v1.0": [ - "Media Function XYZ:Ancillary Data" + "___CHANGE ME FOR A NAME UNIQUE TO YOUR MEDIA FUNCTION INSTANCE___:Ancillary Data" ] }, "format": "urn:x-nmos:format:data", - "label": "MXL VANC Data", + "label": "___CHANGE ME___ Short description of the data flow", "version": "1453880607:123995943", "parents": [], "source_id": "0e635152-e501-4d4e-bb87-9f3fe05eb79a", diff --git a/lib/tests/data/v210_flow.json b/lib/tests/data/v210_flow.json index 103537b1..c18b441d 100644 --- a/lib/tests/data/v210_flow.json +++ b/lib/tests/data/v210_flow.json @@ -1,15 +1,15 @@ { "$copyright": "SPDX-FileCopyrightText: 2025 Contributors to the Media eXchange Layer project.", "$license": "SPDX-License-Identifier: Apache-2.0", - "description": "MXL Test Flow, 1080p29", + "description": "___CHANGE ME___ Long description of the video flow", "id": "5fbec3b1-1b0f-417d-9059-8b94a47197ed", "tags": { "urn:x-nmos:tag:grouphint/v1.0": [ - "Media Function XYZ:Video" + "___CHANGE ME FOR A NAME UNIQUE TO YOUR MEDIA FUNCTION INSTANCE___:Video" ] }, "format": "urn:x-nmos:format:video", - "label": "MXL Test Flow, 1080p29", + "label": "___CHANGE ME___ Short description of the video flow", "parents": [], "media_type": "video/v210", "grain_rate": { diff --git a/lib/tests/data/v210a_flow.json b/lib/tests/data/v210a_flow.json index 7aefd815..c76be883 100644 --- a/lib/tests/data/v210a_flow.json +++ b/lib/tests/data/v210a_flow.json @@ -1,15 +1,15 @@ { "$copyright": "SPDX-FileCopyrightText: 2025 Contributors to the Media eXchange Layer project.", "$license": "SPDX-License-Identifier: Apache-2.0", - "description": "MXL Test Flow, 1080p29 with alpha", + "description": "___CHANGE ME___ Long description of the video flow", "id": "5fbec3b1-1b0f-417d-9059-8b94a47197ed", "tags": { "urn:x-nmos:tag:grouphint/v1.0": [ - "Media Function XYZ:Video" + "___CHANGE ME FOR A NAME UNIQUE TO YOUR MEDIA FUNCTION INSTANCE___:Video" ] }, "format": "urn:x-nmos:format:video", - "label": "MXL Test Flow, 1080p29 with alpha", + "label": "___CHANGE ME___ Short description of the video flow", "parents": [], "media_type": "video/v210a", "grain_rate": {