0
# Google Cloud Video Live Stream
1
2
Google Cloud Video Live Stream API client library that transcodes mezzanine live signals into direct-to-consumer streaming formats, including Dynamic Adaptive Streaming over HTTP (DASH/MPEG-DASH) and HTTP Live Streaming (HLS), for multiple device platforms. This library provides comprehensive Python interface for managing live streaming workflows, channel configurations, input/output management, and real-time transcoding operations.
3
4
## Package Information
5
6
- **Package Name**: google-cloud-video-live-stream
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-video-live-stream`
9
10
## Core Imports
11
12
```python
13
from google.cloud.video import live_stream_v1
14
```
15
16
Individual client imports:
17
18
```python
19
from google.cloud.video.live_stream_v1 import (
20
LivestreamServiceClient,
21
LivestreamServiceAsyncClient
22
)
23
```
24
25
Type imports:
26
27
```python
28
from google.cloud.video.live_stream_v1.types.resources import (
29
Channel, Input, Event, Asset, Pool
30
)
31
from google.cloud.video.live_stream_v1.types.service import (
32
CreateChannelRequest, ListChannelsResponse
33
)
34
```
35
36
## Basic Usage
37
38
```python
39
from google.cloud.video import live_stream_v1
40
from google.cloud.video.live_stream_v1.types.resources import (
41
Channel, Input, InputAttachment
42
)
43
from google.cloud.video.live_stream_v1.types.service import (
44
CreateInputRequest, CreateChannelRequest, StartChannelRequest
45
)
46
from google.cloud.video.live_stream_v1.types.outputs import (
47
ElementaryStream, VideoStream
48
)
49
50
# Create client with default credentials
51
client = live_stream_v1.LivestreamServiceClient()
52
53
# Create an input for receiving streams
54
input_resource = Input(
55
type_=Input.Type.RTMP_PUSH,
56
tier=Input.Tier.HD
57
)
58
input_request = CreateInputRequest(
59
parent="projects/my-project/locations/us-central1",
60
input_id="my-input",
61
input=input_resource
62
)
63
input_operation = client.create_input(request=input_request)
64
created_input = input_operation.result()
65
66
# Create a channel for live streaming
67
channel_resource = Channel(
68
input_attachments=[
69
InputAttachment(
70
key="input1",
71
input=created_input.name
72
)
73
],
74
output=ElementaryStream(
75
video_stream=VideoStream(
76
h264=VideoStream.H264CodecSettings(
77
bitrate_bps=1000000,
78
frame_rate=30,
79
height_pixels=720,
80
width_pixels=1280
81
)
82
)
83
)
84
)
85
channel_request = CreateChannelRequest(
86
parent="projects/my-project/locations/us-central1",
87
channel_id="my-channel",
88
channel=channel_resource
89
)
90
channel_operation = client.create_channel(request=channel_request)
91
created_channel = channel_operation.result()
92
93
# Start the channel
94
start_request = StartChannelRequest(name=created_channel.name)
95
start_operation = client.start_channel(request=start_request)
96
start_response = start_operation.result()
97
```
98
99
## Architecture
100
101
The Live Stream API follows a resource-oriented design with these core components:
102
103
- **Client**: Primary interface (LivestreamServiceClient) with sync/async variants
104
- **Resources**: Channel (streaming pipeline), Input (ingestion endpoint), Event (channel events), Asset (media assets), Pool (resource pools)
105
- **Operations**: Long-running operations for channel lifecycle management
106
- **Types**: Comprehensive type system with resources, outputs, and service request/response objects
107
- **Transport**: Supports gRPC and REST protocols with automatic retry and authentication
108
109
## Capabilities
110
111
### Channel Management
112
113
Complete channel lifecycle management including creation, configuration, starting/stopping, and deletion of live streaming channels with support for multiple output formats and quality levels.
114
115
```python { .api }
116
def create_channel(request: CreateChannelRequest) -> operation.Operation: ...
117
def list_channels(request: ListChannelsRequest) -> pagers.ListChannelsPager: ...
118
def get_channel(request: GetChannelRequest) -> Channel: ...
119
def delete_channel(request: DeleteChannelRequest) -> operation.Operation: ...
120
def update_channel(request: UpdateChannelRequest) -> operation.Operation: ...
121
def start_channel(request: StartChannelRequest) -> operation.Operation: ...
122
def stop_channel(request: StopChannelRequest) -> operation.Operation: ...
123
```
124
125
[Channel Management](./channel-management.md)
126
127
### Input Management
128
129
Management of streaming input endpoints that receive live video streams via protocols like RTMP and SRT, with configuration for preprocessing, security rules, and stream properties.
130
131
```python { .api }
132
def create_input(request: CreateInputRequest) -> operation.Operation: ...
133
def list_inputs(request: ListInputsRequest) -> pagers.ListInputsPager: ...
134
def get_input(request: GetInputRequest) -> Input: ...
135
def delete_input(request: DeleteInputRequest) -> operation.Operation: ...
136
def update_input(request: UpdateInputRequest) -> operation.Operation: ...
137
```
138
139
[Input Management](./input-management.md)
140
141
### Event Management
142
143
Creation and management of channel events for dynamic overlay insertion, ad breaks, and other time-based modifications to live streams during broadcast.
144
145
```python { .api }
146
def create_event(request: CreateEventRequest) -> Event: ...
147
def list_events(request: ListEventsRequest) -> pagers.ListEventsPager: ...
148
def get_event(request: GetEventRequest) -> Event: ...
149
def delete_event(request: DeleteEventRequest) -> None: ...
150
```
151
152
[Event Management](./event-management.md)
153
154
### Asset and DVR Management
155
156
Management of media assets and Digital Video Recording (DVR) sessions for creating recordings, clips, and time-shifted viewing experiences from live streams.
157
158
```python { .api }
159
def create_asset(request: CreateAssetRequest) -> operation.Operation: ...
160
def list_assets(request: ListAssetsRequest) -> pagers.ListAssetsPager: ...
161
def get_asset(request: GetAssetRequest) -> Asset: ...
162
def delete_asset(request: DeleteAssetRequest) -> operation.Operation: ...
163
def create_dvr_session(request: CreateDvrSessionRequest) -> DvrSession: ...
164
def list_dvr_sessions(request: ListDvrSessionsRequest) -> pagers.ListDvrSessionsPager: ...
165
def get_dvr_session(request: GetDvrSessionRequest) -> DvrSession: ...
166
def delete_dvr_session(request: DeleteDvrSessionRequest) -> None: ...
167
def update_dvr_session(request: UpdateDvrSessionRequest) -> DvrSession: ...
168
```
169
170
[Asset and DVR Management](./asset-dvr-management.md)
171
172
### Clip Management
173
174
Creation and management of video clips extracted from live streams or DVR sessions, allowing users to create highlights and shareable content segments.
175
176
```python { .api }
177
def list_clips(request: ListClipsRequest) -> pagers.ListClipsPager: ...
178
def get_clip(request: GetClipRequest) -> Clip: ...
179
def create_clip(request: CreateClipRequest) -> operation.Operation: ...
180
def delete_clip(request: DeleteClipRequest) -> operation.Operation: ...
181
```
182
183
[Clip Management](./clip-management.md)
184
185
### Resource Pool Management
186
187
Management of resource pools that organize and control access to streaming resources across projects and regions.
188
189
```python { .api }
190
def get_pool(request: GetPoolRequest) -> Pool: ...
191
def update_pool(request: UpdatePoolRequest) -> operation.Operation: ...
192
```
193
194
[Resource Pool Management](./pool-management.md)
195
196
### Resource Path Utilities
197
198
Utilities for constructing and parsing Google Cloud resource names used throughout the Live Stream API.
199
200
```python { .api }
201
@staticmethod
202
def asset_path(project: str, location: str, asset: str) -> str: ...
203
@staticmethod
204
def channel_path(project: str, location: str, channel: str) -> str: ...
205
@staticmethod
206
def clip_path(project: str, location: str, channel: str, clip: str) -> str: ...
207
@staticmethod
208
def dvr_session_path(project: str, location: str, channel: str, dvr_session: str) -> str: ...
209
@staticmethod
210
def event_path(project: str, location: str, channel: str, event: str) -> str: ...
211
@staticmethod
212
def input_path(project: str, location: str, input: str) -> str: ...
213
@staticmethod
214
def pool_path(project: str, location: str, pool: str) -> str: ...
215
@staticmethod
216
def network_path(project: str, network: str) -> str: ...
217
@staticmethod
218
def secret_version_path(project: str, secret: str, version: str) -> str: ...
219
@staticmethod
220
def common_billing_account_path(billing_account: str) -> str: ...
221
@staticmethod
222
def common_folder_path(folder: str) -> str: ...
223
@staticmethod
224
def common_organization_path(organization: str) -> str: ...
225
@staticmethod
226
def common_project_path(project: str) -> str: ...
227
@staticmethod
228
def common_location_path(project: str, location: str) -> str: ...
229
230
@staticmethod
231
def parse_asset_path(path: str) -> Dict[str, str]: ...
232
@staticmethod
233
def parse_channel_path(path: str) -> Dict[str, str]: ...
234
@staticmethod
235
def parse_clip_path(path: str) -> Dict[str, str]: ...
236
@staticmethod
237
def parse_dvr_session_path(path: str) -> Dict[str, str]: ...
238
@staticmethod
239
def parse_event_path(path: str) -> Dict[str, str]: ...
240
@staticmethod
241
def parse_input_path(path: str) -> Dict[str, str]: ...
242
@staticmethod
243
def parse_pool_path(path: str) -> Dict[str, str]: ...
244
@staticmethod
245
def parse_network_path(path: str) -> Dict[str, str]: ...
246
@staticmethod
247
def parse_secret_version_path(path: str) -> Dict[str, str]: ...
248
@staticmethod
249
def parse_common_billing_account_path(path: str) -> Dict[str, str]: ...
250
@staticmethod
251
def parse_common_folder_path(path: str) -> Dict[str, str]: ...
252
@staticmethod
253
def parse_common_organization_path(path: str) -> Dict[str, str]: ...
254
@staticmethod
255
def parse_common_project_path(path: str) -> Dict[str, str]: ...
256
@staticmethod
257
def parse_common_location_path(path: str) -> Dict[str, str]: ...
258
```
259
260
### Operations Management
261
262
Standard Google Cloud operations management for long-running operations.
263
264
```python { .api }
265
def list_operations(
266
self,
267
request: operations_pb2.ListOperationsRequest = None,
268
*,
269
retry: OptionalRetry = gapic_v1.method.DEFAULT,
270
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
271
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
272
) -> operations_pb2.ListOperationsResponse: ...
273
274
def get_operation(
275
self,
276
request: operations_pb2.GetOperationRequest = None,
277
*,
278
retry: OptionalRetry = gapic_v1.method.DEFAULT,
279
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
280
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
281
) -> operations_pb2.Operation: ...
282
283
def delete_operation(
284
self,
285
request: operations_pb2.DeleteOperationRequest = None,
286
*,
287
retry: OptionalRetry = gapic_v1.method.DEFAULT,
288
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
289
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
290
) -> None: ...
291
292
def cancel_operation(
293
self,
294
request: operations_pb2.CancelOperationRequest = None,
295
*,
296
retry: OptionalRetry = gapic_v1.method.DEFAULT,
297
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
298
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
299
) -> None: ...
300
```
301
302
### Locations Management
303
304
Standard Google Cloud locations management for service availability.
305
306
```python { .api }
307
def get_location(
308
self,
309
request: locations_pb2.GetLocationRequest = None,
310
*,
311
retry: OptionalRetry = gapic_v1.method.DEFAULT,
312
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
313
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
314
) -> locations_pb2.Location: ...
315
316
def list_locations(
317
self,
318
request: locations_pb2.ListLocationsRequest = None,
319
*,
320
retry: OptionalRetry = gapic_v1.method.DEFAULT,
321
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
322
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
323
) -> locations_pb2.ListLocationsResponse: ...
324
```
325
326
## Core Types
327
328
### Client Types
329
330
```python { .api }
331
class LivestreamServiceClient:
332
"""Main synchronous client for Live Stream API operations."""
333
def __init__(self, *, credentials=None, transport=None, client_options=None) -> None: ...
334
335
class LivestreamServiceAsyncClient:
336
"""Asynchronous client for Live Stream API operations."""
337
def __init__(self, *, credentials=None, transport=None, client_options=None) -> None: ...
338
```
339
340
### Factory Methods
341
342
```python { .api }
343
@classmethod
344
def from_service_account_info(
345
cls,
346
info: dict,
347
*args,
348
**kwargs
349
) -> LivestreamServiceClient:
350
"""Creates a client using service account information from a dictionary."""
351
352
@classmethod
353
def from_service_account_file(
354
cls,
355
filename: str,
356
*args,
357
**kwargs
358
) -> LivestreamServiceClient:
359
"""Creates a client using service account information from a JSON file."""
360
```
361
362
### Client Properties
363
364
```python { .api }
365
@property
366
def transport(self) -> LivestreamServiceTransport:
367
"""The transport used by the client instance."""
368
369
@property
370
def api_endpoint(self) -> str:
371
"""The API endpoint for the service."""
372
373
@property
374
def universe_domain(self) -> str:
375
"""The universe domain for the service."""
376
```
377
378
### Primary Resource Types
379
380
```python { .api }
381
class Channel:
382
"""Live streaming channel configuration and state."""
383
name: str
384
create_time: timestamp_pb2.Timestamp
385
update_time: timestamp_pb2.Timestamp
386
labels: MutableMapping[str, str]
387
input_attachments: MutableSequence[InputAttachment]
388
active_input: str
389
output: ElementaryStream
390
elementary_streams: MutableSequence[ElementaryStream]
391
mux_streams: MutableSequence[MuxStream]
392
manifests: MutableSequence[Manifest]
393
sprite_sheets: MutableSequence[SpriteSheet]
394
streaming_state: StreamingState
395
streaming_error: status_pb2.Status
396
log_config: LogConfig
397
timecode_config: TimecodeConfig
398
encryptions: MutableSequence[Encryption]
399
400
class Input:
401
"""Streaming input endpoint configuration."""
402
name: str
403
create_time: timestamp_pb2.Timestamp
404
update_time: timestamp_pb2.Timestamp
405
labels: MutableMapping[str, str]
406
type_: Type
407
tier: Tier
408
uri: str
409
preprocessing_config: PreprocessingConfig
410
security_rules: SecurityRule
411
input_stream_property: InputStreamProperty
412
413
class Event:
414
"""Channel event for dynamic content insertion."""
415
name: str
416
create_time: timestamp_pb2.Timestamp
417
update_time: timestamp_pb2.Timestamp
418
labels: MutableMapping[str, str]
419
input_switch: InputSwitchTask
420
ad_break: AdBreakTask
421
return_to_program: ReturnToProgramTask
422
slate: SlateTask
423
mute: MuteTask
424
unmute: UnmuteTask
425
execute_now: bool
426
execution_time: timestamp_pb2.Timestamp
427
state: State
428
error: status_pb2.Status
429
430
class Asset:
431
"""Media asset resource."""
432
name: str
433
create_time: timestamp_pb2.Timestamp
434
update_time: timestamp_pb2.Timestamp
435
labels: MutableMapping[str, str]
436
video: VideoAsset
437
crc32c: str
438
state: State
439
error: status_pb2.Status
440
441
class DvrSession:
442
"""Digital Video Recording session."""
443
name: str
444
create_time: timestamp_pb2.Timestamp
445
update_time: timestamp_pb2.Timestamp
446
labels: MutableMapping[str, str]
447
start_time: timestamp_pb2.Timestamp
448
end_time: timestamp_pb2.Timestamp
449
retention_config: RetentionConfig
450
dvr_end_time: timestamp_pb2.Timestamp
451
state: State
452
error: status_pb2.Status
453
454
class Pool:
455
"""Resource pool for organizing streaming resources."""
456
name: str
457
create_time: timestamp_pb2.Timestamp
458
update_time: timestamp_pb2.Timestamp
459
labels: MutableMapping[str, str]
460
network_config: NetworkConfig
461
462
class Clip:
463
"""Video clip extracted from streams."""
464
name: str
465
create_time: timestamp_pb2.Timestamp
466
update_time: timestamp_pb2.Timestamp
467
labels: MutableMapping[str, str]
468
start_time_offset: duration_pb2.Duration
469
end_time_offset: duration_pb2.Duration
470
clip_manifest_uri: str
471
state: State
472
error: status_pb2.Status
473
```
474
475
### Request/Response Types
476
477
```python { .api }
478
# Channel requests
479
class CreateChannelRequest:
480
parent: str
481
channel_id: str
482
channel: Channel
483
request_id: str
484
485
class ListChannelsRequest:
486
parent: str
487
page_size: int
488
page_token: str
489
filter: str
490
order_by: str
491
492
class ListChannelsResponse:
493
channels: MutableSequence[Channel]
494
next_page_token: str
495
unreachable: MutableSequence[str]
496
497
class GetChannelRequest:
498
name: str
499
500
class DeleteChannelRequest:
501
name: str
502
request_id: str
503
504
class UpdateChannelRequest:
505
update_mask: field_mask_pb2.FieldMask
506
channel: Channel
507
request_id: str
508
509
class StartChannelRequest:
510
name: str
511
request_id: str
512
513
class StopChannelRequest:
514
name: str
515
request_id: str
516
```
517
518
### Output Configuration Types
519
520
```python { .api }
521
class ElementaryStream:
522
"""Elementary stream configuration for video and audio streams."""
523
key: str
524
video_stream: VideoStream
525
audio_stream: AudioStream
526
text_stream: TextStream
527
528
class VideoStream:
529
"""Video stream configuration and encoding settings."""
530
h264: H264CodecSettings
531
h265: H265CodecSettings
532
533
class H264CodecSettings:
534
"""H.264 video codec configuration."""
535
bitrate_bps: int
536
frame_rate: float
537
height_pixels: int
538
width_pixels: int
539
aq_mode: str
540
b_frames: int
541
b_pyramid: bool
542
entropy_coder: str
543
gop_duration: duration_pb2.Duration
544
keyframe_interval: int
545
pixel_format: str
546
preset: str
547
profile: str
548
rate_control_mode: str
549
tune: str
550
551
class H265CodecSettings:
552
"""H.265 video codec configuration."""
553
bitrate_bps: int
554
frame_rate: float
555
height_pixels: int
556
width_pixels: int
557
558
class AudioStream:
559
"""Audio stream configuration and encoding settings."""
560
codec: str
561
bitrate_bps: int
562
channel_count: int
563
channel_layout: MutableSequence[str]
564
sample_rate_hertz: int
565
language_code: str
566
567
class TextStream:
568
"""Text stream configuration for subtitles and captions."""
569
codec: str
570
language_code: str
571
mapping: MutableSequence[TextMapping]
572
573
class TextMapping:
574
"""Text stream mapping configuration."""
575
atom_key: str
576
input_key: str
577
input_track: int
578
579
class MuxStream:
580
"""Multiplexed stream configuration combining elementary streams."""
581
key: str
582
container: str
583
elementary_streams: MutableSequence[str]
584
segment_settings: SegmentSettings
585
encryption_id: str
586
587
class Manifest:
588
"""Output manifest configuration for HLS and DASH."""
589
file_name: str
590
type_: ManifestType
591
mux_streams: MutableSequence[str]
592
max_segment_count: int
593
segment_keep_count: int
594
595
class ManifestType(proto.Enum):
596
"""Manifest type enumeration."""
597
MANIFEST_TYPE_UNSPECIFIED = 0
598
HLS = 1
599
DASH = 2
600
601
class SegmentSettings:
602
"""Segment configuration for streaming outputs."""
603
segment_duration: duration_pb2.Duration
604
individual_segments: bool
605
606
class SpriteSheet:
607
"""Sprite sheet configuration for video thumbnails."""
608
format_: str
609
file_prefix: str
610
sprite_width_pixels: int
611
sprite_height_pixels: int
612
column_count: int
613
row_count: int
614
start_time_offset: duration_pb2.Duration
615
end_time_offset: duration_pb2.Duration
616
total_count: int
617
interval: duration_pb2.Duration
618
quality: int
619
620
class TimecodeConfig:
621
"""Timecode configuration for live streams."""
622
source: TimecodeSource
623
utc_offset: duration_pb2.Duration
624
time_zone: TimeZone
625
626
class TimecodeSource(proto.Enum):
627
"""Timecode source enumeration."""
628
TIMECODE_SOURCE_UNSPECIFIED = 0
629
EMBEDDED = 1
630
MEDIA_TIMESTAMP = 2
631
632
class TimeZone:
633
"""Time zone configuration."""
634
id: str
635
636
class Encryption:
637
"""Encryption configuration for stream security."""
638
id: str
639
secret_manager_key_source: SecretManagerSource
640
drm_systems: DrmSystems
641
aes128: Aes128Encryption
642
sample_aes: SampleAesEncryption
643
mpeg_cenc: MpegCommonEncryption
644
645
class SecretManagerSource:
646
"""Secret Manager key source."""
647
secret: str
648
version: str
649
650
class LogConfig:
651
"""Logging configuration for channels."""
652
log_severity: LogSeverity
653
654
class LogSeverity(proto.Enum):
655
"""Log severity levels."""
656
LOG_SEVERITY_UNSPECIFIED = 0
657
OFF = 1
658
DEBUG = 100
659
INFO = 200
660
WARNING = 400
661
ERROR = 500
662
663
class StaticOverlay:
664
"""Static overlay configuration for channels."""
665
asset: str
666
resolution: NormalizedResolution
667
position: NormalizedCoordinate
668
opacity: float
669
670
class NormalizedCoordinate:
671
"""Normalized coordinate for positioning overlays."""
672
x: float
673
y: float
674
675
class NormalizedResolution:
676
"""Normalized resolution for overlay sizing."""
677
w: float
678
h: float
679
680
class TimeInterval:
681
"""Time interval specification."""
682
start_time: timestamp_pb2.Timestamp
683
end_time: timestamp_pb2.Timestamp
684
685
class NetworkConfig:
686
"""Network configuration for resource pools."""
687
peered_network: str
688
```
689
690
### Operation Types
691
692
```python { .api }
693
class OperationMetadata:
694
"""Metadata for long-running operations."""
695
create_time: timestamp_pb2.Timestamp
696
end_time: timestamp_pb2.Timestamp
697
target: str
698
verb: str
699
status_message: str
700
requested_cancellation: bool
701
api_version: str
702
703
class ChannelOperationResponse:
704
"""Response for channel operations."""
705
pass
706
```