pyst2110 0.9.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyst2110/__init__.py +113 -0
- pyst2110/_chunk.py +146 -0
- pyst2110/_layout.py +85 -0
- pyst2110/framing.py +352 -0
- pyst2110/geometry.py +240 -0
- pyst2110/payload.py +556 -0
- pyst2110/py.typed +0 -0
- pyst2110/redundancy.py +139 -0
- pyst2110/rtp.py +245 -0
- pyst2110/sdp.py +1052 -0
- pyst2110/timing.py +844 -0
- pyst2110/transmit.py +329 -0
- pyst2110-0.9.1.dist-info/METADATA +149 -0
- pyst2110-0.9.1.dist-info/RECORD +16 -0
- pyst2110-0.9.1.dist-info/WHEEL +4 -0
- pyst2110-0.9.1.dist-info/licenses/LICENSE +21 -0
pyst2110/__init__.py
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"""SMPTE ST 2110 protocol: RTP and RFC 4175 headers, geometry, SDP.
|
|
2
|
+
|
|
3
|
+
The layer between a transport and a raster. A NIC binding, a socket or a
|
|
4
|
+
capture file supplies packets; this says what their headers mean and where
|
|
5
|
+
their payloads belong; the consumer moves the pixels (SPEC
|
|
6
|
+
§spec:scope-boundary).
|
|
7
|
+
|
|
8
|
+
Nothing here needs a NIC, a licence or a vendor SDK.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from pyst2110.framing import FrameTracker as FrameTracker
|
|
12
|
+
from pyst2110.framing import SequenceTracker as SequenceTracker
|
|
13
|
+
from pyst2110.framing import frame_boundaries as frame_boundaries
|
|
14
|
+
from pyst2110.framing import frame_starts as frame_starts
|
|
15
|
+
from pyst2110.geometry import byte_offset as byte_offset
|
|
16
|
+
from pyst2110.geometry import choose_payload_size as choose_payload_size
|
|
17
|
+
from pyst2110.geometry import fits_raster as fits_raster
|
|
18
|
+
from pyst2110.geometry import line_bytes as line_bytes
|
|
19
|
+
from pyst2110.geometry import packets_per_frame as packets_per_frame
|
|
20
|
+
from pyst2110.geometry import packets_per_line as packets_per_line
|
|
21
|
+
from pyst2110.geometry import pgroup as pgroup
|
|
22
|
+
from pyst2110.geometry import raster_offset as raster_offset
|
|
23
|
+
from pyst2110.geometry import rows_per_field as rows_per_field
|
|
24
|
+
from pyst2110.geometry import sample_offset as sample_offset
|
|
25
|
+
from pyst2110.payload import PayloadHeaders as PayloadHeaders
|
|
26
|
+
from pyst2110.payload import parse_payload_headers as parse_payload_headers
|
|
27
|
+
from pyst2110.redundancy import LegPair as LegPair
|
|
28
|
+
from pyst2110.redundancy import reconstruct as reconstruct
|
|
29
|
+
from pyst2110.rtp import FIXED_HEADER_SIZE as FIXED_HEADER_SIZE
|
|
30
|
+
from pyst2110.rtp import RtpHeaders as RtpHeaders
|
|
31
|
+
from pyst2110.rtp import parse_rtp as parse_rtp
|
|
32
|
+
from pyst2110.sdp import RTP_CLOCK_RATE as RTP_CLOCK_RATE
|
|
33
|
+
from pyst2110.sdp import SENDER_TYPE_NARROW as SENDER_TYPE_NARROW
|
|
34
|
+
from pyst2110.sdp import SENDER_TYPE_NARROW_LINEAR as SENDER_TYPE_NARROW_LINEAR
|
|
35
|
+
from pyst2110.sdp import SENDER_TYPE_WIDE as SENDER_TYPE_WIDE
|
|
36
|
+
from pyst2110.sdp import SENDER_TYPES as SENDER_TYPES
|
|
37
|
+
from pyst2110.sdp import STANDARD_UDP_SIZE_LIMIT as STANDARD_UDP_SIZE_LIMIT
|
|
38
|
+
from pyst2110.sdp import SdpConformanceWarning as SdpConformanceWarning
|
|
39
|
+
from pyst2110.sdp import SdpFlow as SdpFlow
|
|
40
|
+
from pyst2110.sdp import SdpVideo as SdpVideo
|
|
41
|
+
from pyst2110.sdp import format_dup_sdp as format_dup_sdp
|
|
42
|
+
from pyst2110.sdp import format_sdp as format_sdp
|
|
43
|
+
from pyst2110.sdp import parse_dup_sdp as parse_dup_sdp
|
|
44
|
+
from pyst2110.sdp import parse_sdp as parse_sdp
|
|
45
|
+
from pyst2110.sdp import parse_video_format as parse_video_format
|
|
46
|
+
from pyst2110.timing import Limits as Limits
|
|
47
|
+
from pyst2110.timing import Measurement as Measurement
|
|
48
|
+
from pyst2110.timing import Schedule as Schedule
|
|
49
|
+
from pyst2110.timing import Vrx as Vrx
|
|
50
|
+
from pyst2110.timing import c_inst as c_inst
|
|
51
|
+
from pyst2110.timing import measure as measure
|
|
52
|
+
from pyst2110.timing import read_schedule as read_schedule
|
|
53
|
+
from pyst2110.timing import read_times as read_times
|
|
54
|
+
from pyst2110.timing import sender_limits as sender_limits
|
|
55
|
+
from pyst2110.timing import video_datum as video_datum
|
|
56
|
+
from pyst2110.timing import vrx as vrx
|
|
57
|
+
from pyst2110.transmit import PACKET_HEADER_SIZE as PACKET_HEADER_SIZE
|
|
58
|
+
from pyst2110.transmit import UDP_HEADER_SIZE as UDP_HEADER_SIZE
|
|
59
|
+
from pyst2110.transmit import FrameHeaders as FrameHeaders
|
|
60
|
+
from pyst2110.transmit import max_payload_size as max_payload_size
|
|
61
|
+
|
|
62
|
+
__all__ = [
|
|
63
|
+
"FIXED_HEADER_SIZE",
|
|
64
|
+
"PACKET_HEADER_SIZE",
|
|
65
|
+
"RTP_CLOCK_RATE",
|
|
66
|
+
"SENDER_TYPES",
|
|
67
|
+
"SENDER_TYPE_NARROW",
|
|
68
|
+
"SENDER_TYPE_NARROW_LINEAR",
|
|
69
|
+
"SENDER_TYPE_WIDE",
|
|
70
|
+
"STANDARD_UDP_SIZE_LIMIT",
|
|
71
|
+
"UDP_HEADER_SIZE",
|
|
72
|
+
"FrameHeaders",
|
|
73
|
+
"FrameTracker",
|
|
74
|
+
"LegPair",
|
|
75
|
+
"Limits",
|
|
76
|
+
"Measurement",
|
|
77
|
+
"PayloadHeaders",
|
|
78
|
+
"RtpHeaders",
|
|
79
|
+
"Schedule",
|
|
80
|
+
"SdpConformanceWarning",
|
|
81
|
+
"SdpFlow",
|
|
82
|
+
"SdpVideo",
|
|
83
|
+
"SequenceTracker",
|
|
84
|
+
"Vrx",
|
|
85
|
+
"byte_offset",
|
|
86
|
+
"c_inst",
|
|
87
|
+
"choose_payload_size",
|
|
88
|
+
"fits_raster",
|
|
89
|
+
"format_dup_sdp",
|
|
90
|
+
"format_sdp",
|
|
91
|
+
"frame_boundaries",
|
|
92
|
+
"frame_starts",
|
|
93
|
+
"line_bytes",
|
|
94
|
+
"max_payload_size",
|
|
95
|
+
"measure",
|
|
96
|
+
"packets_per_frame",
|
|
97
|
+
"packets_per_line",
|
|
98
|
+
"parse_dup_sdp",
|
|
99
|
+
"parse_payload_headers",
|
|
100
|
+
"parse_rtp",
|
|
101
|
+
"parse_sdp",
|
|
102
|
+
"parse_video_format",
|
|
103
|
+
"pgroup",
|
|
104
|
+
"raster_offset",
|
|
105
|
+
"read_schedule",
|
|
106
|
+
"read_times",
|
|
107
|
+
"reconstruct",
|
|
108
|
+
"rows_per_field",
|
|
109
|
+
"sample_offset",
|
|
110
|
+
"sender_limits",
|
|
111
|
+
"video_datum",
|
|
112
|
+
"vrx",
|
|
113
|
+
]
|
pyst2110/_chunk.py
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
"""Shape checks and per-packet reads shared by the header parses.
|
|
2
|
+
|
|
3
|
+
Internal. Both parses take the same thing — a ``(packets, stride)`` uint8 view
|
|
4
|
+
(SPEC §spec:interface-shape) — and both need to read a big-endian field at an
|
|
5
|
+
offset that differs per packet, because CSRCs, a header extension and the
|
|
6
|
+
RFC 4175 continuation bit all move what follows them.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
import numpy as np
|
|
14
|
+
from numpy.typing import ArrayLike, DTypeLike, NDArray
|
|
15
|
+
|
|
16
|
+
_U16_SIZE = 2
|
|
17
|
+
_U32_SIZE = 4
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def per_packet(
|
|
21
|
+
values: ArrayLike,
|
|
22
|
+
noun: str,
|
|
23
|
+
count: int | None = None,
|
|
24
|
+
plural: str = "",
|
|
25
|
+
dtype: DTypeLike = np.int64,
|
|
26
|
+
) -> NDArray[Any]:
|
|
27
|
+
"""One ``noun`` per packet, coerced — or a ValueError naming the field.
|
|
28
|
+
|
|
29
|
+
Every array crossing this interface is packet-aligned
|
|
30
|
+
(§spec:interface-shape), so every one of them is checked the same way.
|
|
31
|
+
Pass ``count`` where the packet count is already known, which reports both
|
|
32
|
+
numbers; without it the check is that the input is one-dimensional at all,
|
|
33
|
+
which is what catches a ``(packets, stride)`` view passed by mistake.
|
|
34
|
+
|
|
35
|
+
``plural`` names ``noun`` in the plural where adding an *s* does not.
|
|
36
|
+
"""
|
|
37
|
+
array = np.asarray(values, dtype=dtype)
|
|
38
|
+
if count is None:
|
|
39
|
+
if array.ndim != 1:
|
|
40
|
+
raise ValueError(f"expected one {noun} per packet, got shape {array.shape}")
|
|
41
|
+
elif array.shape != (count,):
|
|
42
|
+
raise ValueError(
|
|
43
|
+
f"expected one {noun} per packet: {count} packets, "
|
|
44
|
+
f"{array.size} {plural or noun + 's'}"
|
|
45
|
+
)
|
|
46
|
+
return array
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def validate(packets: NDArray[np.uint8], minimum: int) -> None:
|
|
50
|
+
"""Reject anything that is not a byte chunk of at least ``minimum`` columns."""
|
|
51
|
+
if packets.ndim != 2:
|
|
52
|
+
raise ValueError(
|
|
53
|
+
f"expected a (packets, stride) byte view, got shape {packets.shape}"
|
|
54
|
+
)
|
|
55
|
+
if packets.dtype != np.uint8:
|
|
56
|
+
raise ValueError(
|
|
57
|
+
f"expected a uint8 byte view, got dtype {packets.dtype}; a wider "
|
|
58
|
+
"dtype would misalign every field"
|
|
59
|
+
)
|
|
60
|
+
if packets.shape[1] < minimum:
|
|
61
|
+
raise ValueError(
|
|
62
|
+
f"expected at least {minimum} columns, got shape {packets.shape}"
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def limits(
|
|
67
|
+
packets: NDArray[np.uint8], sizes: NDArray[np.integer[Any]] | None
|
|
68
|
+
) -> NDArray[np.int64]:
|
|
69
|
+
"""Each packet's usable length: its reported size, or the stride if unstated.
|
|
70
|
+
|
|
71
|
+
A receiver writes at most the stride and reports the true size separately,
|
|
72
|
+
so the columns past a packet still hold whatever the buffer held before
|
|
73
|
+
(§spec:interface-shape). Deriving a field's position from those would read
|
|
74
|
+
the previous frame's packet.
|
|
75
|
+
"""
|
|
76
|
+
count, stride = packets.shape
|
|
77
|
+
if sizes is None:
|
|
78
|
+
return np.full(count, stride, dtype=np.int64)
|
|
79
|
+
bounds: NDArray[np.int64] = per_packet(sizes, "size", count=count)
|
|
80
|
+
return np.clip(bounds, 0, stride)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def read_u16(
|
|
84
|
+
packets: NDArray[np.uint8],
|
|
85
|
+
offsets: NDArray[np.int64],
|
|
86
|
+
bounds: NDArray[np.int64],
|
|
87
|
+
rows: NDArray[np.int64] | None = None,
|
|
88
|
+
) -> tuple[NDArray[np.int64], NDArray[np.bool_]]:
|
|
89
|
+
"""A big-endian 16-bit field read at a per-packet offset.
|
|
90
|
+
|
|
91
|
+
Returns the values and a mask of which reads landed inside their packet.
|
|
92
|
+
A read that does not fit is clamped to a valid index and its value zeroed
|
|
93
|
+
rather than raising: one malformed packet in a chunk of thousands is a
|
|
94
|
+
packet to account for, not a reason to drop the chunk.
|
|
95
|
+
|
|
96
|
+
``rows`` is the packet index the gather reads down, ``arange(count)``
|
|
97
|
+
where a caller does not pass one. A caller reading several fields of the
|
|
98
|
+
same chunk passes it once rather than paying an allocation per field:
|
|
99
|
+
:func:`pyst2110.payload.parse_payload_headers` reads nine, and at a
|
|
100
|
+
thousand chunks a second that is nine arange allocations per chunk on the
|
|
101
|
+
frame path.
|
|
102
|
+
"""
|
|
103
|
+
inside = (offsets >= 0) & (offsets + _U16_SIZE <= bounds)
|
|
104
|
+
index = np.where(inside, offsets, 0).clip(0, packets.shape[1] - _U16_SIZE)
|
|
105
|
+
if rows is None:
|
|
106
|
+
rows = np.arange(packets.shape[0])
|
|
107
|
+
high = packets[rows, index].astype(np.int64)
|
|
108
|
+
low = packets[rows, index + 1].astype(np.int64)
|
|
109
|
+
return np.where(inside, (high << 8) | low, 0).astype(np.int64), inside
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def u16_view(packets: NDArray[np.uint8]) -> NDArray[np.uint16] | None:
|
|
113
|
+
"""The whole chunk as big-endian 16-bit words, or ``None`` if it cannot be.
|
|
114
|
+
|
|
115
|
+
Reinterpreting the buffer is what turns a header field into a column
|
|
116
|
+
slice, and a column slice is what the conforming fast path is made of
|
|
117
|
+
(§spec:conforming-fast-path). It needs the rows contiguous and an even
|
|
118
|
+
number of octets in each; a caller handing over an odd stride, or a
|
|
119
|
+
sub-block sliced out of a wider buffer, gets ``None`` and the general path
|
|
120
|
+
rather than an exception. Both are legitimate chunks — they are simply not
|
|
121
|
+
ones a column slice can read.
|
|
122
|
+
"""
|
|
123
|
+
if packets.shape[1] % _U16_SIZE != 0 or not packets.flags["C_CONTIGUOUS"]:
|
|
124
|
+
return None
|
|
125
|
+
view: NDArray[np.uint16] = packets.view(">u2")
|
|
126
|
+
return view
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def u32_view(packets: NDArray[np.uint8]) -> NDArray[np.uint32] | None:
|
|
130
|
+
"""The whole chunk as big-endian 32-bit words, or ``None`` if it cannot be.
|
|
131
|
+
|
|
132
|
+
The same reinterpretation :func:`u16_view` makes, one width up, for the
|
|
133
|
+
fields that are thirty-two bits on the wire — the RTP timestamp and the
|
|
134
|
+
SSRC. Reading one as two sixteen-bit columns joined in place costs a
|
|
135
|
+
widen, a shift and an or over the chunk; reading it as one column costs a
|
|
136
|
+
strided copy and nothing else.
|
|
137
|
+
|
|
138
|
+
A stricter guard than the sixteen-bit one, and it has to be: a stride that
|
|
139
|
+
is a multiple of two but not of four reinterprets to a shape numpy
|
|
140
|
+
refuses, so it takes the sixteen-bit path instead. The chunk's own base is
|
|
141
|
+
numpy's to align.
|
|
142
|
+
"""
|
|
143
|
+
if packets.shape[1] % _U32_SIZE != 0 or not packets.flags["C_CONTIGUOUS"]:
|
|
144
|
+
return None
|
|
145
|
+
view: NDArray[np.uint32] = packets.view(">u4")
|
|
146
|
+
return view
|
pyst2110/_layout.py
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
"""Where the wire fields sit, declared once for the reader and the writer.
|
|
2
|
+
|
|
3
|
+
Internal. RFC 3550 section 5.1 fixes the RTP header's octets and RFC 4175
|
|
4
|
+
section 4.2 the payload header's, and a parse and a builder that each restate
|
|
5
|
+
them agree with each other whatever either one says: a round trip through both
|
|
6
|
+
passes a matched pair of wrong offsets, and only a hand-written vector catches
|
|
7
|
+
it (§spec:testing). So the octets are stated here and imported.
|
|
8
|
+
|
|
9
|
+
Offsets are relative to the unit that owns them — the RTP fields to the start
|
|
10
|
+
of the fixed header, the SRD fields to the start of their own six-octet
|
|
11
|
+
header — so a module reading a packet-relative position adds its own base.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
#: Octets of RFC 3550 fixed header, before any CSRC list or extension.
|
|
17
|
+
FIXED_HEADER_SIZE = 12
|
|
18
|
+
|
|
19
|
+
# Within the fixed header.
|
|
20
|
+
SEQUENCE = 2
|
|
21
|
+
TIMESTAMP = 4
|
|
22
|
+
SSRC = 8
|
|
23
|
+
|
|
24
|
+
# Byte 0: V(2) P(1) X(1) CC(4). Byte 1: M(1) PT(7).
|
|
25
|
+
VERSION_SHIFT = 6
|
|
26
|
+
PADDING_MASK = 0x20
|
|
27
|
+
EXTENSION_MASK = 0x10
|
|
28
|
+
CSRC_COUNT_MASK = 0x0F
|
|
29
|
+
MARKER_MASK = 0x80
|
|
30
|
+
PAYLOAD_TYPE_MASK = 0x7F
|
|
31
|
+
|
|
32
|
+
#: The version every packet under this standard carries, in place: ST 2110-20
|
|
33
|
+
#: section 6.1.2 provides for an extension but requires none, so P, X and CC
|
|
34
|
+
#: are clear beside it.
|
|
35
|
+
RTP_VERSION = 2
|
|
36
|
+
VERSION_2 = RTP_VERSION << VERSION_SHIFT
|
|
37
|
+
|
|
38
|
+
#: RFC 3551 section 6 leaves 96-127 dynamic, which is where a raw video format
|
|
39
|
+
#: is bound; the first of them is what an offer and a header both default to.
|
|
40
|
+
DYNAMIC_PAYLOAD_TYPE = 96
|
|
41
|
+
|
|
42
|
+
# RFC 4175 section 4.2: two octets of Extended Sequence Number, then one or
|
|
43
|
+
# more six-octet Sample Row Data headers.
|
|
44
|
+
EXTENDED_SEQUENCE_SIZE = 2
|
|
45
|
+
SRD_SIZE = 6
|
|
46
|
+
# Within one SRD header.
|
|
47
|
+
SRD_LENGTH = 0
|
|
48
|
+
SRD_ROW = 2
|
|
49
|
+
SRD_OFFSET = 4
|
|
50
|
+
|
|
51
|
+
# The F bit tops the row word and the C bit tops the offset word, leaving
|
|
52
|
+
# fifteen bits of value under each. The SRD Length has no flag above it.
|
|
53
|
+
FLAG_MASK = 0x8000
|
|
54
|
+
VALUE_MASK = 0x7FFF
|
|
55
|
+
|
|
56
|
+
#: One past the largest a field of this width holds — the modulus a value
|
|
57
|
+
#: written into one wraps in, and the bound a caller's own is checked against.
|
|
58
|
+
U16_MODULUS = 1 << 16
|
|
59
|
+
U32_MODULUS = 1 << 32
|
|
60
|
+
|
|
61
|
+
#: Octets a conforming ST 2110-20 packet's header occupies, whole: the RFC
|
|
62
|
+
#: 3550 fixed header with neither a CSRC list nor an extension after it, the
|
|
63
|
+
#: extended sequence number, and one SRD header. Stated once because a parse
|
|
64
|
+
#: reading it and a builder writing it agreeing with each other is the whole
|
|
65
|
+
#: point of this module — two restatements agree until one of them is edited.
|
|
66
|
+
CONFORMING_HEADER_SIZE = FIXED_HEADER_SIZE + EXTENDED_SEQUENCE_SIZE + SRD_SIZE
|
|
67
|
+
|
|
68
|
+
#: Where the one SRD header begins in such a packet.
|
|
69
|
+
SRD_BASE = FIXED_HEADER_SIZE + EXTENDED_SEQUENCE_SIZE
|
|
70
|
+
|
|
71
|
+
#: The width of the field the wire carries most of its numbers in, and the
|
|
72
|
+
#: modulus that follows from it. A sequence space, a half of a thirty-two-bit
|
|
73
|
+
#: number and the stride of a column read are all this one fact.
|
|
74
|
+
U16_BITS = 16
|
|
75
|
+
U16_SIZE = U16_BITS // 8
|
|
76
|
+
|
|
77
|
+
#: Word positions in a big-endian sixteen-bit view of a conforming header —
|
|
78
|
+
#: the octet offsets above, halved. Stated here beside the octets they come
|
|
79
|
+
#: from, so the column read is covered by the same single statement the
|
|
80
|
+
#: gather is.
|
|
81
|
+
SEQUENCE_WORD = SEQUENCE // U16_SIZE
|
|
82
|
+
EXTENDED_SEQUENCE_WORD = FIXED_HEADER_SIZE // U16_SIZE
|
|
83
|
+
SRD_LENGTH_WORD = (SRD_BASE + SRD_LENGTH) // U16_SIZE
|
|
84
|
+
SRD_ROW_WORD = (SRD_BASE + SRD_ROW) // U16_SIZE
|
|
85
|
+
SRD_OFFSET_WORD = (SRD_BASE + SRD_OFFSET) // U16_SIZE
|