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