0
# Event Management
1

2
Creation and management of channel events for dynamic overlay insertion, ad breaks, and other time-based modifications to live streams during broadcast.
3

4
## Capabilities
5

6
### Creating Events
7

8
Creates a new event for a channel that can perform actions like input switching, ad breaks, slate insertion, or mute/unmute operations.
9

10
```python { .api }
11
def create_event(
12
    self,
13
    request: Union[CreateEventRequest, dict] = None,
14
    *,
15
    parent: str = None,
16
    event: Event = None,
17
    event_id: str = None,
18
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
19
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
20
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
21
) -> Event:
22
    """
23
    Creates an event with the provided unique ID in the specified channel.
24

25
    Args:
26
        request: The request object containing parent, event_id, event, and request_id
27
        parent: Required. The parent channel (projects/{project}/locations/{location}/channels/{channel})
28
        event: Required. The event resource to create
29
        event_id: Required. The ID to use for the event (must be unique within parent)
30
        retry: Retry configuration for the request
31
        timeout: Request timeout in seconds
32
        metadata: Additional metadata for the request
33

34
    Returns:
35
        Event: The created event resource
36
        
37
    Raises:
38
        google.api_core.exceptions.GoogleAPICallError: If the request fails
39
    """
40
```
41

42
### Listing Events
43

44
Retrieves a list of events for a channel with pagination and filtering capabilities.
45

46
```python { .api }
47
def list_events(
48
    self,
49
    request: Union[ListEventsRequest, dict] = None,
50
    *,
51
    parent: str = None,
52
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
53
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
54
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
55
) -> pagers.ListEventsPager:
56
    """
57
    Returns a list of all events in the specified channel.
58

59
    Args:
60
        request: The request object containing parent, page_size, page_token, filter, order_by
61
        parent: Required. The parent channel (projects/{project}/locations/{location}/channels/{channel})
62
        retry: Retry configuration for the request
63
        timeout: Request timeout in seconds
64
        metadata: Additional metadata for the request
65

66
    Returns:
67
        pagers.ListEventsPager: Pager for iterating over event results
68
        
69
    Raises:
70
        google.api_core.exceptions.GoogleAPICallError: If the request fails
71
    """
72
```
73

74
### Getting Event Details
75

76
Retrieves detailed information about a specific event including its configuration, state, and execution status.
77

78
```python { .api }
79
def get_event(
80
    self,
81
    request: Union[GetEventRequest, dict] = None,
82
    *,
83
    name: str = None,
84
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
85
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
86
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
87
) -> Event:
88
    """
89
    Returns the specified event.
90

91
    Args:
92
        request: The request object containing name
93
        name: Required. The event name (projects/{project}/locations/{location}/channels/{channel}/events/{event})
94
        retry: Retry configuration for the request
95
        timeout: Request timeout in seconds
96
        metadata: Additional metadata for the request
97

98
    Returns:
99
        Event: The event resource
100
        
101
    Raises:
102
        google.api_core.exceptions.GoogleAPICallError: If the request fails
103
    """
104
```
105

106
### Deleting Events
107

108
Permanently removes an event from a channel, canceling it if currently scheduled or executing.
109

110
```python { .api }
111
def delete_event(
112
    self,
113
    request: Union[DeleteEventRequest, dict] = None,
114
    *,
115
    name: str = None,
116
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
117
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
118
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
119
) -> None:
120
    """
121
    Deletes the specified event.
122

123
    Args:
124
        request: The request object containing name and request_id
125
        name: Required. The event name (projects/{project}/locations/{location}/channels/{channel}/events/{event})
126
        retry: Retry configuration for the request
127
        timeout: Request timeout in seconds
128
        metadata: Additional metadata for the request
129

130
    Returns:
131
        None
132
        
133
    Raises:
134
        google.api_core.exceptions.GoogleAPICallError: If the request fails
135
    """
136
```
137

138
## Event Configuration Types
139

140
### Event Resource
141

142
```python { .api }
143
class Event:
144
    """
145
    Event resource for dynamic channel modifications during live streaming.
146
    
147
    Attributes:
148
        name (str): Event resource name
149
        create_time (google.protobuf.timestamp_pb2.Timestamp): Creation timestamp
150
        update_time (google.protobuf.timestamp_pb2.Timestamp): Last update timestamp
151
        labels (MutableMapping[str, str]): User-defined labels
152
        input_switch (InputSwitchTask): Input switching task configuration
153
        ad_break (AdBreakTask): Ad break task configuration
154
        return_to_program (ReturnToProgramTask): Return to program task configuration
155
        slate (SlateTask): Slate insertion task configuration  
156
        mute (MuteTask): Audio mute task configuration
157
        unmute (UnmuteTask): Audio unmute task configuration
158
        execute_now (bool): Execute immediately upon creation
159
        execution_time (google.protobuf.timestamp_pb2.Timestamp): Scheduled execution time
160
        state (State): Current event state
161
        error (google.rpc.status_pb2.Status): Any execution errors
162
    """
163
    
164
    class State(proto.Enum):
165
        """Event state enumeration."""
166
        STATE_UNSPECIFIED = 0
167
        SCHEDULED = 1
168
        RUNNING = 2
169
        SUCCEEDED = 3
170
        FAILED = 4
171
        PENDING = 5
172
        STOPPED = 6
173
```
174

175
### Event Task Types
176

177
```python { .api }
178
class InputSwitchTask:
179
    """
180
    Task to switch the active input source.
181
    
182
    Attributes:
183
        input_key (str): Input attachment key to switch to
184
    """
185

186
class AdBreakTask:
187
    """
188
    Task to insert an ad break with duration and slate content.
189
    
190
    Attributes:
191
        duration (google.protobuf.duration_pb2.Duration): Ad break duration
192
        assets (MutableSequence[str]): Asset resource names for ad content
193
    """
194

195
class ReturnToProgramTask:
196
    """
197
    Task to return to the main program content after an ad break.
198
    """
199

200
class SlateTask:
201
    """
202
    Task to display a static slate image or video.
203
    
204
    Attributes:
205
        duration (google.protobuf.duration_pb2.Duration): Slate display duration
206
        asset (str): Asset resource name containing slate content
207
    """
208

209
class MuteTask:
210
    """
211
    Task to mute audio output.
212
    
213
    Attributes:
214
        duration (google.protobuf.duration_pb2.Duration): Mute duration
215
    """
216

217
class UnmuteTask:
218
    """
219
    Task to unmute audio output.
220
    """
221
```
222

223
## Usage Examples
224

225
### Creating Input Switch Event
226

227
```python
228
from google.cloud.video import live_stream_v1
229
from google.protobuf import timestamp_pb2
230
import datetime
231

232
client = live_stream_v1.LivestreamServiceClient()
233

234
# Schedule input switch for specific time
235
execution_time = datetime.datetime.now() + datetime.timedelta(minutes=5)
236
execution_timestamp = timestamp_pb2.Timestamp()
237
execution_timestamp.FromDatetime(execution_time)
238

239
event = live_stream_v1.Event(
240
    input_switch=live_stream_v1.InputSwitchTask(
241
        input_key="backup-input"
242
    ),
243
    execution_time=execution_timestamp
244
)
245

246
request = live_stream_v1.CreateEventRequest(
247
    parent="projects/my-project/locations/us-central1/channels/my-channel",
248
    event_id="switch-to-backup",
249
    event=event
250
)
251

252
event_result = client.create_event(request=request)
253
print(f"Created event: {event_result.name}")
254
```
255

256
### Creating Ad Break Event
257

258
```python
259
from google.protobuf import duration_pb2
260

261
# Create 30-second ad break with assets
262
ad_duration = duration_pb2.Duration(seconds=30)
263

264
event = live_stream_v1.Event(
265
    ad_break=live_stream_v1.AdBreakTask(
266
        duration=ad_duration,
267
        assets=[
268
            "projects/my-project/locations/us-central1/assets/commercial-1",
269
            "projects/my-project/locations/us-central1/assets/commercial-2"
270
        ]
271
    ),
272
    execute_now=True  # Execute immediately
273
)
274

275
request = live_stream_v1.CreateEventRequest(
276
    parent="projects/my-project/locations/us-central1/channels/my-channel",
277
    event_id="ad-break-30s",
278
    event=event
279
)
280

281
event_result = client.create_event(request=request)
282
```
283

284
### Creating Slate Event
285

286
```python
287
# Display slate for 10 seconds
288
slate_duration = duration_pb2.Duration(seconds=10)
289

290
event = live_stream_v1.Event(
291
    slate=live_stream_v1.SlateTask(
292
        duration=slate_duration,
293
        asset="projects/my-project/locations/us-central1/assets/technical-difficulties"
294
    ),
295
    execute_now=True
296
)
297

298
request = live_stream_v1.CreateEventRequest(
299
    parent="projects/my-project/locations/us-central1/channels/my-channel",
300
    event_id="technical-difficulties",
301
    event=event
302
)
303
```
304

305
### Creating Mute/Unmute Events
306

307
```python
308
# Mute audio for 5 seconds
309
mute_duration = duration_pb2.Duration(seconds=5)
310

311
mute_event = live_stream_v1.Event(
312
    mute=live_stream_v1.MuteTask(
313
        duration=mute_duration
314
    ),
315
    execute_now=True
316
)
317

318
# Create unmute event to restore audio
319
unmute_event = live_stream_v1.Event(
320
    unmute=live_stream_v1.UnmuteTask(),
321
    execute_now=False,
322
    execution_time=timestamp_pb2.Timestamp()  # Set appropriate time
323
)
324

325
# Create both events
326
mute_request = live_stream_v1.CreateEventRequest(
327
    parent="projects/my-project/locations/us-central1/channels/my-channel",
328
    event_id="mute-audio",
329
    event=mute_event
330
)
331

332
unmute_request = live_stream_v1.CreateEventRequest(
333
    parent="projects/my-project/locations/us-central1/channels/my-channel",
334
    event_id="unmute-audio", 
335
    event=unmute_event
336
)
337
```
338

339
### Monitoring Event Execution
340

341
```python
342
# Check event state
343
event_name = "projects/my-project/locations/us-central1/channels/my-channel/events/my-event"
344

345
get_request = live_stream_v1.GetEventRequest(name=event_name)
346
event = client.get_event(request=get_request)
347

348
print(f"Event state: {event.state}")
349
if event.error.code != 0:
350
    print(f"Event error: {event.error.message}")
351

352
# List all events in channel
353
list_request = live_stream_v1.ListEventsRequest(
354
    parent="projects/my-project/locations/us-central1/channels/my-channel"
355
)
356

357
for event in client.list_events(request=list_request):
358
    print(f"Event {event.name}: {event.state}")
359
```