From ded9f7d2c86e2e92182633b2cecc8ead6ca0e6ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philip=20J=C3=A4genstedt?= Date: Fri, 25 Sep 2015 12:07:52 +0200 Subject: [PATCH] Add MediaSession.activate() Also: * Let MediaSession.deactivate() return a promise. * Drop implicit activation and decativation for AudioContext. Fixes https://github.com/whatwg/mediasession/issues/50 --- mediasession.bs | 170 +++++++++++++++++++++------------------------- mediasession.html | 116 +++++++++++++------------------ 2 files changed, 124 insertions(+), 162 deletions(-) diff --git a/mediasession.bs b/mediasession.bs index f908f12..6c2a2e4 100644 --- a/mediasession.bs +++ b/mediasession.bs @@ -215,7 +215,8 @@ conforming IDL fragments, as described in the Web IDL specification. [[!WEBIDL]] interface MediaSession { readonly attribute MediaSessionKind kind; - void deactivate(); + Promise<void> activate(); + Promise<void> deactivate(); }; enum MediaSessionKind { @@ -243,14 +244,19 @@ sessions.
Returns the media session's kind.
+
+ session . {{MediaSession/activate()}} +
+
+ Requests platform-level media focus and sets the media session's + state to active. +
session . {{MediaSession/deactivate()}}
- Releases platform-level media focus, sets the media session's - state to idle and - applies any changes necessary to its - audio-producing participants. + Releases platform-level media focus and sets the media session's + state to idle.
@@ -263,8 +269,56 @@ session state">idle. The kind attribute must return the media session's kind. +The activate() method, when +invoked, must run these steps: + +
    +
  1. + Let media session be the context object. +
    2. +
  2. + Let promise be a new promise. +
    3. +
  3. + Return promise, and run the remaining steps in parallel. +
    4. +
  4. + Activate media session. +
    5. +
  5. + If activate failed, reject promise with a + TypeError. +
    6. +
  6. + Otherwise, fulfill promise with undefined. +
    7. +
+ +Note: {{activate()}} can fail if there is an ongoing high-priority activity, +e.g. a phone call. + The deactivate() method, when -invoked, must deactivate the context object. +invoked, must run these steps: + +
    +
  1. + Let media session be the context object. +
    2. +
  2. + Let promise be a new promise. +
    3. +
  3. + Return promise, and run the remaining steps in parallel. +
    4. +
  4. + Deactivate media session. +
    5. +
  5. + Fulfill promise with undefined. +
    6. +
+ +Note: Unlike {{activate()}}, {{deactivate()}} cannot fail.

States

@@ -570,8 +624,7 @@ the original corresponding duck request.

Activating a media session

-The media session activation algorithm takes one argument, -media session, and consists of the following steps: +To activate a media session, run these steps:
  1. @@ -647,11 +700,11 @@ The media session activation algorithm takes one argument,

    Interrupting a media session

    -A media session may be interrupted at any time after its -media session activation algorithm has been run. This typically occurs -when another application or another media session requests and is granted -a level of platform media focus that affects the media session based on -its kind. +An active media +session may be interrupted at any time. This typically occurs when another +application or another media session requests and is granted a level of +platform media focus that affects the media session based on its +kind. Interruptions can be both transient or permanent. A transient interruption means we can either choose to duck our media content and continue playing it @@ -699,10 +752,9 @@ The media session interruption algorithm takes one argument, state">idle.

    - This implies that the next time the media session activation - algorithm is run against media session that we will - re-request media focus according to the steps defined in that - algorithm. + This implies that the next time the media session is + activated, that we will re-request media focus according to + the steps defined in that algorithm.

  2. @@ -1031,9 +1083,9 @@ The media session deactivation algorithm takes one argument, idle.

    - This implies that the next time the media session activation - algorithm is run against media session that we will - re-request media focus according to the steps defined in that algorithm. + This implies that the next time the media session is + activated, that we will re-request media focus according to the + steps defined in that algorithm.

@@ -1103,13 +1155,14 @@ following steps, passing in media element as media element: element to this list.
  • - Let activated be the result of running the media session - activation algorithm for media session. + Activate media session.
  • - If activated is failure, pause current media - element. + If activate failed, pause media element.
    • + @@ -1206,38 +1259,6 @@ agent must run the following steps: -

    Activating a -media session from an {{AudioContext}} object

    - - - -When the {{resume()}} method on an {{AudioContext}} object is invoked from -script and that {{AudioContext}} object's {{state}} attribute is "{{suspended}}" -then the user agent must run the following steps: - -
      -
    1. - Let audio object be the current {{AudioContext}} object. -
      2. -
    2. - Let media session be the value of audio object's - current media session. -
      3. -
    3. - If audio object is not currently in media session's - list of audio-producing participants, then append audio - object to this list. -
      4. -
    4. - Let activated be the result of running the media session - activation algorithm for media session. -
      5. -
    5. - If activated is failure, pause audio object. -
      6. -
    - -

    Interrupting a media session from an {{AudioContext}} object

    @@ -1249,43 +1270,6 @@ When the user agent is to resume a web audio object for a given {{AudioContext}} object it must invoke that {{AudioContext}} object's {{resume()}} method. -

    Deactivating a -media session from an {{AudioContext}} object

    - -When an {{AudioContext}} object's {{state}} attribute transitions to -"{{closed}}", the user agent must release web audio object from its media -session. - -When the user agent is to release web audio object from its media -session for a given {{AudioContext}} object it must run the following -steps: - -
      -
    1. - Let audio object be the current {{AudioContext}} object. -
      2. -
    2. - Let media session be the value of audio object's - current media session. -
      3. -
    3. - If audio object is not currently in media session's - list of audio-producing participants, then terminate these steps. -
      4. -
    4. - If audio object is in media session's resume - list then remove it from this list. -
      5. -
    5. - Remove audio object from media session's list of - audio-producing participants. -
      6. -
    6. - Run the media session deactivation algorithm for media - session. -
      7. -
    -

    Examples

    This section is non-normative. diff --git a/mediasession.html b/mediasession.html index cdd2a71..3ece44c 100644 --- a/mediasession.html +++ b/mediasession.html @@ -73,7 +73,7 @@

    Media Session

    -

    Living Standard — Last Updated

    +

    Living Standard — Last Updated

    Participate: @@ -124,11 +124,7 @@

    6 Extensions to the AudioContext interface
  • 7 Examples @@ -209,7 +205,8 @@

    MediaSession { readonly attribute MediaSessionKind kind; - void deactivate(); + Promise<void> activate(); + Promise<void> deactivate(); }; enum MediaSessionKind { @@ -226,14 +223,35 @@

    Returns a new MediaSession object.
    session . kind
    Returns the media session’s kind. +
    session . activate() +
    Requests platform-level media focus and sets the media session’s state to active.
    session . deactivate() -
    Releases platform-level media focus, sets the media session’s state to idle and - applies any changes necessary to its audio-producing participants. +
    Releases platform-level media focus and sets the media session’s state to idle.

    • The MediaSession(kind) constructor, when invoked, must return a new media session whose kind is kind, and state is idle.

    The kind attribute must return the media session’s kind.

    +

    The activate() method, when +invoked, must run these steps:

    +
      +
    1. Let media session be the context object. +
    2. Let promise be a new promise. +
    3. Return promise, and run the remaining steps in parallel. +
    4. Activate media session. +
    5. If activate failed, reject promise with a TypeError. +
    6. Otherwise, fulfill promise with undefined. +
    +

    Note: activate() can fail if there is an ongoing high-priority activity, +e.g. a phone call.

    The deactivate() method, when -invoked, must deactivate the context object.

    +invoked, must run these steps:

    +
      +
    1. Let media session be the context object. +
    2. Let promise be a new promise. +
    3. Return promise, and run the remaining steps in parallel. +
    4. Deactivate media session. +
    5. Fulfill promise with undefined. +
    +

    Note: Unlike activate(), deactivate() cannot fail.

    4.1. States

    A media session has a state that describes its current status with respect to any platform-level interactions and @@ -384,7 +402,7 @@

    4.4. Activating a media session

    -

    The media session activation algorithm takes one argument, media session, and consists of the following steps:

    +

    To activate a media session, run these steps:

    1. If media session is already active, then return success.
    2. @@ -428,10 +446,10 @@

      4.5. Interrupting a media session

      -

      A media session may be interrupted at any time after its media session activation algorithm has been run. This typically occurs -when another application or another media session requests and is granted -a level of platform media focus that affects the media session based on -its kind.

      +

      An active media +session may be interrupted at any time. This typically occurs when another +application or another media session requests and is granted a level of +platform media focus that affects the media session based on its kind.

      Interruptions can be both transient or permanent. A transient interruption means we can either choose to duck our media content and continue playing it out at a reduced volume for the duration of the interruption; or pause our media content for the duration of the interruption and, then, resume @@ -455,10 +473,8 @@

      < If media session’s kind is "content" then indefinitely pause all of media session’s audio-producing participants and set media session’s state to idle. -

      This implies that the next time the media session activation - algorithm is run against media session that we will - re-request media focus according to the steps defined in that - algorithm.

      +

      This implies that the next time the media session is activated, that we will re-request media focus according to + the steps defined in that algorithm.

    3. Optionally, based on platform conventions, the user agent must remove any previously established ongoing media interface in the underlying platform’s notifications area and any ongoing media @@ -621,9 +637,8 @@

      < have any remaining audio-producing participants.

    4. Set media session’s state to idle. -

      This implies that the next time the media session activation - algorithm is run against media session that we will - re-request media focus according to the steps defined in that algorithm.

      +

      This implies that the next time the media session is activated, that we will re-request media focus according to the + steps defined in that algorithm.

    5. Extensions to the HTMLMediaElement interface

    partial interface HTMLMediaElement {
@@ -658,10 +673,8 @@ 
    audio-producing participants, then append media
     element to this list. 
-    
  •  Let activated be the result of running the media session
-    activation algorithm for media session. 
-    
  •  If activated is failure, pause current media
-    element. 
+    
  •  Activate media session. 
+    
  •  If activate failed, pause media element. 
    
    
    5.2. Interrupting a
 media session from an HTMLMediaElement object
    
@@ -709,44 +722,10 @@ 
    AudioContext object’s current media session to the new
     value. 
    
-   
    6.1. Activating a
-media session from an AudioContext object
    
-   
    When the resume() method on an AudioContext object is invoked from
-script and that AudioContext object’s state attribute is "suspended"
-then the user agent must run the following steps:
    
-   
      
-    
    1.  Let audio object be the current AudioContext object. 
-    
    2.  Let media session be the value of audio object’s current media session. 
-    
    3.  If audio object is not currently in media session’s
-    list of audio-producing participants, then append audio
-    object to this list. 
-    
    4.  Let activated be the result of running the media session
-    activation algorithm for media session. 
-    
    5.  If activated is failure, pause audio object. 
-   
    
-   
    6.2. Interrupting a
+   
    6.1. Interrupting a
 media session from an AudioContext object
    
    
    When the user agent is to suspend a web audio object for a given AudioContext object it must invoke that AudioContext object’s suspend() method.
    
    
    When the user agent is to resume a web audio object for a given AudioContext object it must invoke that AudioContext object’s resume() method.
    
-   
    6.3. Deactivating a
-media session from an AudioContext object
    
-   
    When an AudioContext object’s state attribute transitions to
-"closed", the user agent must release web audio object from its media
-session.
    
-   
    When the user agent is to release web audio object from its media
-session for a given AudioContext object it must run the following
-steps:
    
-   
      
-    
    1.  Let audio object be the current AudioContext object. 
-    
    2.  Let media session be the value of audio object’s current media session. 
-    
    3.  If audio object is not currently in media session’s
-    list of audio-producing participants, then terminate these steps. 
-    
    4.  If audio object is in media session’s resume
-    list then remove it from this list. 
-    
    5.  Remove audio object from media session’s list of audio-producing participants. 
-    
    6.  Run the media session deactivation algorithm for media
-    session. 
-   
    
    
    7. Examples
    
    
    This section is non-normative.
    
    
    
@@ -802,6 +781,8 @@ 
    Ac
   
    Index
    
   
    Terms defined by this specification
    
   
    
  • state, in §4.1
-   
  • suspend a web audio object, in §6.2
+   
  • suspend a web audio object, in §6.1
    
  • transient, in §4.2
    
  • transient-solo, in §4.2
    
  • unduck, in §4.3
@@ -864,6 +842,7 @@ 
    case-sensitive
      
  • controls
      
  • ended playback
+     
  • in parallel
      
  • internal pause steps
      
  • media element
      
  • media element load algorithm
@@ -885,12 +864,10 @@ 
    [webaudio] defines the following terms:
     
    
  • 
     [dom-ls] defines the following terms:
@@ -919,7 +896,8 @@ 
    IDL Inde
 interface MediaSession {
   readonly attribute MediaSessionKind kind;
 
-  void deactivate();
+  Promise<void> activate();
+  Promise<void> deactivate();
 };
 
 enum MediaSessionKind {