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 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