Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion docs/source/media/camera.rst
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,14 @@ before the motion event:
camera = Camera({..., "recording": {"delegate": recording}}, driver, "Camera")

The channel comes from the same provider as the live sessions, so a channel
that is also watched live is pulled once. Observed with iOS and tvOS 27: hubs
that is also watched live is pulled once. It must deliver H.265: a recording
whose first fragment has not come ``first_video_timeout`` seconds (10 s by
default) after the hub asked, e.g. from an H.264 camera or one that sends
nothing or stalls once its channel is open, fails and the hub is told so
instead of waiting. Opening the channel counts toward that time but is not cut
short: an input resolver and the media worker's own request timeout decide how
long it takes. A camera whose keyframe interval is longer than the bound needs
a prebuffer. Observed with iOS and tvOS 27: hubs
do not upload the HDS recordings of a camera that also has ``multi_tier``,
so they never appear in the Home app. Use recording on cameras without it.

Expand Down
52 changes: 48 additions & 4 deletions pyhap/media/recording_delegate.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,10 @@
logger = logging.getLogger(__name__)

DEFAULT_PREBUFFER_MS = 0
# Seconds from the hub's request to a recording's first media fragment. A
# hub waits little longer: one gave up at about 17 s when the first fragment
# came after about 10 s.
DEFAULT_FIRST_VIDEO_TIMEOUT = 10.0
# Seconds before a buffered channel whose recorder ended is opened again,
# doubling up to the maximum while it keeps failing.
REOPEN_DELAY = 1.0
Expand Down Expand Up @@ -125,6 +129,23 @@ class RecordingMediaDelegate:
with iOS and tvOS 26 and 27) and record from the trigger on. ``ffmpeg``
defaults to the provider's; ``video_encoder`` and ``encoder_args`` pick
the H.264 encoder, e.g. a hardware one.

The channel must deliver H.265, the only video the source reads. A
recording whose first media fragment has not come
``first_video_timeout`` seconds after the hub asked for it, e.g. from an
H.264 camera or one that sends nothing or stalls, ends with a
:class:`RecordingError` instead of leaving the hub waiting. The bound
counts from the request but cuts short only the wait for media, not
opening the channel: how long that takes is up to the application's
resolver and, with a media worker, the worker's own request timeout.

A recording starts at an IRAP picture: a filled prebuffer holds one,
otherwise the recording waits for the camera's next one, so a camera
whose IRAP interval is longer than ``first_video_timeout`` needs a
prebuffer. The default is 10 s because a hub gave up at about 17 s on a
recording whose first fragment came after about 10 s, so a first
fragment after 14 s, as from a camera with a 12 s IRAP interval, is
unlikely to be accepted either.
"""

def __init__(
Expand All @@ -136,14 +157,21 @@ def __init__(
ffmpeg: str | None = None,
video_encoder: str = "libx264",
encoder_args: Sequence[str] = (),
first_video_timeout: float = DEFAULT_FIRST_VIDEO_TIMEOUT,
) -> None:
"""Configure the delegate; :meth:`arm` starts buffering."""
"""Configure the delegate; :meth:`arm` starts buffering.

:raises ValueError: If ``first_video_timeout`` is not positive.
"""
if not first_video_timeout > 0: # also refuses NaN
raise ValueError("first_video_timeout must be positive")
self._provider = source_provider
self.tier = tier
self.prebuffer_ms = prebuffer_ms
self.ffmpeg = ffmpeg or source_provider.ffmpeg
self.video_encoder = video_encoder
self.encoder_args = tuple(encoder_args)
self.first_video_timeout = first_video_timeout
self._lease: ChannelLease | None = None
self._recorder: RecorderLike | None = None
self._armed = False
Expand Down Expand Up @@ -270,8 +298,10 @@ async def record(

Without a buffered channel the channel is pulled for this recording
only, which then starts at the next IRAP picture. Raises
:class:`RecordingError` when the transcode fails.
:class:`RecordingError` when the transcode fails or its first media
fragment has not come ``first_video_timeout`` seconds after the call.
"""
deadline = asyncio.get_running_loop().time() + self.first_video_timeout
async with self._lock:
recorder = await self._open()
if recorder.recording:
Expand Down Expand Up @@ -311,10 +341,24 @@ def ended(error: str | None) -> None:
if not self.buffering:
await self._release()
raise
packets = fmp4_recording_packets(reader)
received = 0
try:
async for packet in fmp4_recording_packets(reader):
if packet.is_last and errors:
while True:
# The init segment and the first fragment are due by the
# deadline. It never spans a yield, and a timeout ends
# ``packets`` by cancelling it.
try:
async with asyncio.timeout_at(deadline if received < 2 else None):
packet = await anext(packets, None)
except TimeoutError:
raise RecordingError(
f"No video to record within {self.first_video_timeout:g} s:"
" the camera sent no H.265 IRAP picture or stopped after one"
) from None
if packet is None or (packet.is_last and errors):
break
received += 1
yield packet
if errors:
raise RecordingError(errors[0])
Expand Down
232 changes: 224 additions & 8 deletions tests/test_media_recording_delegate.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,33 +19,97 @@
from pyhap.media.worker import MediaWorker
from pyhap.util import base64_to_bytes, to_base64_str

from .media_hap import GOP_FRAMES, SyntheticPull, bridged
from .media_peer import KEYFRAME, wait_until
from .media_hap import FRAME_INTERVAL, GOP_FRAMES, SyntheticPull, bridged
from .media_peer import KEYFRAME, TRAIL, Source, wait_until
from .test_media_recording import selected

pytestmark = pytest.mark.timeout(30)

# Stands in for ffmpeg: an init segment, then one fragment per input read
# whose mdat holds the MPEG-TS it read.
# Stands in for ffmpeg: like it, nothing before the first input, then an init
# segment and one fragment per input read whose mdat holds the MPEG-TS it read.
FAKE_TRANSCODER = """
import os, struct
def box(kind, body):
return struct.pack(">I", 8 + len(body)) + kind + body
os.write(1, box(b"ftyp", b"isom") + box(b"moov", b""))
init = box(b"ftyp", b"isom") + box(b"moov", b"")
while data := os.read(0, 65536):
os.write(1, init + box(b"moof", b"") + box(b"mdat", data))
init = b""
"""
# Stands in for ffmpeg reading a camera that stalls: on the first input the
# init segment and argv[1] fragments, then fragments from 1.5 s later.
PAUSING_TRANSCODER = """
import os, struct, sys, time
def box(kind, body):
return struct.pack(">I", 8 + len(body)) + kind + body
fragment = box(b"moof", b"") + box(b"mdat", os.read(0, 65536))
os.write(1, box(b"ftyp", b"isom") + box(b"moov", b"") + fragment * int(sys.argv[1]))
time.sleep(1.5)
while data := os.read(0, 65536):
os.write(1, box(b"moof", b"") + box(b"mdat", data))
"""
MEDIUM = hksv3.VideoStreamTier(2, hksv3.VideoQuality.MEDIUM, 1500, 1280, 720, 30)
# NAL units of an H.264 camera, which hold no H.265 IRAP picture.
H264_IDR = bytes([0x65, 0x88]) + bytes(200)
H264_SLICE = bytes([0x41, 0x9A]) + bytes(200)
# Frames a camera sends before its first IRAP picture when it is joined late.
LATE_IRAP = 15
NO_VIDEO = (
"No video to record within 0.2 s: the camera sent no H.265 IRAP picture"
" or stopped after one"
)


def h265(frame: int) -> list[bytes]:
"""A frame of a camera with an IRAP picture every GOP_FRAMES frames."""
return KEYFRAME if frame % GOP_FRAMES == 0 else [TRAIL]


def late_irap(frame: int) -> list[bytes]:
"""A frame of a camera joined LATE_IRAP frames before its IRAP picture."""
return [TRAIL] if frame < LATE_IRAP else h265(frame - LATE_IRAP)


def h264(frame: int) -> list[bytes]:
"""A frame of an H.264 camera."""
return [H264_IDR] if frame % GOP_FRAMES == 0 else [H264_SLICE]


def no_video(_frame: int) -> list[bytes]:
"""No frame: a camera that sends nothing, or a connection that hangs."""
return []


class ScriptedPull(SyntheticPull):
"""Plays a camera channel that sends ``script(n)`` as its n-th frame."""

def __init__(self, script: Callable[[int], list[bytes]]) -> None:
"""Not running yet."""
super().__init__()
self._script = script

async def _send(self, source: Source) -> None:
try:
while True:
if nals := self._script(self.frames):
source.send_video(nals)
self.frames += 1
await asyncio.sleep(FRAME_INTERVAL)
finally:
source.close()


class Provider:
"""Leases one synthetic channel per tier quality, without audio."""

ffmpeg = "ffmpeg"

def __init__(self, pool: SourcePool) -> None:
"""Remember the pulls it makes."""
def __init__(
self, pool: SourcePool, pull: Callable[[], SyntheticPull] = SyntheticPull
) -> None:
"""Remember the pulls it makes with ``pull``."""
self.pool = pool
self.pull = pull
self.pulls: dict[str, SyntheticPull] = {}

async def lease_channel(
Expand All @@ -55,7 +119,7 @@ async def lease_channel(
name = hksv3.VideoQuality(tier.quality).name.lower()

def make() -> SyntheticPull:
self.pulls[name] = SyntheticPull()
self.pulls[name] = self.pull()
return self.pulls[name]

return await self.pool.lease(name, make, audio=False, name=name)
Expand Down Expand Up @@ -425,3 +489,155 @@ async def test_slow_hub_ends_the_recording(
async for _packet in stream:
await asyncio.sleep(0.2)
await delegate.disarm()


@pytest.mark.parametrize("prebuffer_ms", [0, 1000])
@pytest.mark.parametrize("script", [no_video, h264], ids=["no-video", "h264"])
async def test_recording_without_video_fails(
pool: SourcePool,
fake_transcoder: list[list[str]],
prebuffer_ms: int,
script: Callable[[int], list[bytes]],
) -> None:
"""Verify a recording that gets no H.265 video in time ends with an error."""
provider = Provider(pool, lambda: ScriptedPull(script))
delegate = RecordingMediaDelegate(
provider, MEDIUM, prebuffer_ms=prebuffer_ms, first_video_timeout=0.2
)
await delegate.arm()
with pytest.raises(RecordingError) as error:
await anext(delegate.record(selected(), audio=True))
assert str(error.value) == NO_VIDEO
assert not delegate.recording
await delegate.close()
assert pool.counts() == {}


@pytest.mark.parametrize(
("prebuffer_ms", "held"),
[(0, {}), (1000, {"medium": (1, 1)})],
ids=["released", "buffering"],
)
async def test_recording_after_one_without_video(
pool: SourcePool,
fake_transcoder: list[list[str]],
prebuffer_ms: int,
held: dict[str, tuple[int, int]],
) -> None:
"""Verify a recording that got no video leaves the delegate ready to record."""
video = False
provider = Provider(
pool, lambda: ScriptedPull(lambda frame: h265(frame) if video else [])
)
delegate = RecordingMediaDelegate(
provider, MEDIUM, prebuffer_ms=prebuffer_ms, first_video_timeout=0.2
)
await delegate.arm()
with pytest.raises(RecordingError, match=NO_VIDEO):
await anext(delegate.record(selected(), audio=True))
assert not delegate.recording
# A prebuffering delegate keeps its channel, any other gave it back.
assert pool.counts() == held
video = True
delegate.first_video_timeout = delegate_module.DEFAULT_FIRST_VIDEO_TIMEOUT
stream = delegate.record(selected(), audio=True)
init = await anext(stream)
assert init.data.startswith(b"\x00\x00\x00\x0cftyp")
first = await anext(stream)
assert mpegts.START_CODE + KEYFRAME[0] in first.data
await stream.aclose()
await delegate.close()
assert pool.counts() == {}


async def test_late_first_irap_within_the_bound_records(
pool: SourcePool, fake_transcoder: list[list[str]]
) -> None:
"""Verify a channel whose first IRAP picture comes late, but in time, records."""
provider = Provider(pool, lambda: ScriptedPull(late_irap))
delegate = RecordingMediaDelegate(provider, MEDIUM, first_video_timeout=5.0)
stream = delegate.record(selected(), audio=True)
init = await anext(stream)
assert init.data.startswith(b"\x00\x00\x00\x0cftyp")
# Video came all the while, the recording waited for the IRAP picture.
assert provider.pulls["medium"].frames > LATE_IRAP
first = await anext(stream)
assert mpegts.START_CODE + KEYFRAME[0] in first.data
await stream.aclose()
assert pool.counts() == {}


def pausing_transcoder(monkeypatch: pytest.MonkeyPatch, fragments: int) -> None:
"""Replace the ffmpeg command with the pausing transcoder."""
command = [sys.executable, "-c", PAUSING_TRANSCODER, str(fragments)]
monkeypatch.setattr(
delegate_module, "recording_ffmpeg_args", lambda *_a, **_k: command
)


async def test_init_segment_without_fragment_fails(
pool: SourcePool, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Verify a recording whose first fragment does not come in time fails."""
pausing_transcoder(monkeypatch, fragments=0)
delegate = RecordingMediaDelegate(Provider(pool), MEDIUM, first_video_timeout=1.0)
stream = delegate.record(selected(), audio=True)
init = await anext(stream)
assert init.data.startswith(b"\x00\x00\x00\x0cftyp")
# Its first fragment would come after the pause, past the bound.
with pytest.raises(RecordingError, match="No video to record within 1 s"):
await anext(stream)
assert not delegate.recording
assert pool.counts() == {}


async def test_bound_counts_from_the_request(
pool: SourcePool, fake_transcoder: list[list[str]]
) -> None:
"""Verify the time to open the channel counts toward the bound."""

class Slow(Provider):
async def lease_channel(
self, tier: hksv3.VideoStreamTier, _audio: Any = None
) -> Any:
await asyncio.sleep(1.0)
return await super().lease_channel(tier, _audio)

# The IRAP picture comes LATE_IRAP frames, 0.3 s, after the open: in time
# counted from the open, too late counted from the request.
provider = Slow(pool, lambda: ScriptedPull(late_irap))
delegate = RecordingMediaDelegate(provider, MEDIUM, first_video_timeout=1.0)
with pytest.raises(RecordingError, match="No video to record within 1 s"):
await anext(delegate.record(selected(), audio=True))
assert pool.counts() == {}


async def test_bound_ends_with_the_first_fragment(
pool: SourcePool, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Verify a recording whose first fragment came in time goes on past the bound."""
pausing_transcoder(monkeypatch, fragments=1)
delegate = RecordingMediaDelegate(Provider(pool), MEDIUM, first_video_timeout=1.0)
stream = delegate.record(selected(), audio=True)
await anext(stream)
await anext(stream)
# The next fragment comes after the pause, past the bound.
assert b"moof" in (await anext(stream)).data[:16]
await stream.aclose()
assert pool.counts() == {}


def test_first_video_timeout_defaults_to_10_s() -> None:
"""Verify a recording gets 10 s to its first fragment by default."""
delegate = RecordingMediaDelegate(Provider(SourcePool()), MEDIUM)
assert delegate.first_video_timeout == 10.0
assert delegate_module.DEFAULT_FIRST_VIDEO_TIMEOUT == 10.0


@pytest.mark.parametrize("seconds", [0, -1.0, float("nan")])
def test_first_video_timeout_must_be_positive(seconds: float) -> None:
"""Verify a bound that is not a positive number is refused."""
with pytest.raises(ValueError, match="first_video_timeout"):
RecordingMediaDelegate(
Provider(SourcePool()), MEDIUM, first_video_timeout=seconds
)
Loading