July 2023 Release of the APL 2023.2 compliant APL Viewhost Web

For more details on this release refer to CHANGELOG.md

To learn about APL see: https://developer.amazon.com/docs/alexa-presentation-language/understand-apl.html

Author: amzn-admfox

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog for apl-viewhost-web
 
+## [2023.2]
+This release adds support for version 2023.2 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
+
+### Added
+- Add support for the seekTo ControlMedia command
+
+### Changed
+- Remove usage of APL Core Library's deprecated getTheme API
+- Bug fixes
+
 ## [2023.1]
 This release adds support for version 2023.1 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
 

README.md

@@ -1,10 +1,10 @@
 # Alexa Presentation Language (APL) Viewhost Web
 
 <p>
- <a href="https://github.com/alexa/apl-viewhost-web/tree/v2023.1.0" alt="version">
- <img src="https://img.shields.io/badge/stable%20version-2023.1.0-brightgreen" /></a>
- <a href="https://github.com/alexa/apl-core-library/tree/v2023.1.0" alt="APLCore">
- <img src="https://img.shields.io/badge/apl%20core%20library-2023.1.0-navy" /></a>
+ <a href="https://github.com/alexa/apl-viewhost-web/tree/v2023.2.0" alt="version">
+ <img src="https://img.shields.io/badge/stable%20version-2023.2.0-brightgreen" /></a>
+ <a href="https://github.com/alexa/apl-core-library/tree/v2023.2.0" alt="APLCore">
+ <img src="https://img.shields.io/badge/apl%20core%20library-2023.2.0-navy" /></a>
 </p>
 
 ## Introduction
@@ -16,7 +16,7 @@ platform or framework for which the view host was designed by leveraging the fun
 
 ### Prerequisites
 
-* [NodeJS](https://nodejs.org/en/) - version 16.x or higher
+* [NodeJS](https://nodejs.org/en/) - version 14.x or higher
 * [cmake](https://cmake.org/install/) - the easiest way to install on Mac is using `brew install cmake`
 * [Yarn](https://yarnpkg.com/getting-started/install)
 

js/apl-html/lib/dts/Context.d.ts

@@ -38,8 +38,6 @@ declare namespace APL {
 
         public topComponent(): APL.Component;
 
-        public getTheme(): string;
-
         public getBackground(): APL.IBackground;
 
         public setBackground(background: APL.IBackground): void;

js/apl-html/src/APLRenderer.ts

@@ -527,13 +527,7 @@ export default abstract class APLRenderer<Options = any> {
             });
         }
 
-        let docTheme: string = this.context.getTheme();
-        if (docTheme !== 'light' && docTheme !== 'dark') {
-            // treat themes other than dark and light as dark
-            docTheme = 'dark';
-        }
-
-        this.setBackground(docTheme);
+        this.setBackground();
 
         // begin update loop
         this.requestId = requestAnimationFrame(this.update);
@@ -593,15 +587,15 @@ export default abstract class APLRenderer<Options = any> {
         return Object.keys(this.componentMap).length;
     }
 
-    private setBackground(docTheme: string) {
+    private setBackground() {
+        // Setting backgroundColor to black to ensure the correct behaviour
+        // of a gradient containing an alpha channel component
+
+        this.view.style.backgroundColor = 'black';
+
         const background = this.context.getBackground();
-        const backgroundColors = {
-            dark: 'black',
-            light: 'white'
-        };
         // Spec: If the background property is partially transparent
         // the default background color of the device will show through
-        this.view.style.backgroundColor = backgroundColors[docTheme];
         this.view.style.backgroundImage = background.gradient ?
             getCssGradient(background.gradient, this.logger) :
             getCssPureColorGradient(background.color);

js/apl-html/src/components/EditText.ts

@@ -263,10 +263,7 @@ export class EditText extends ActionableComponent<IEditTextProperties> {
     }
 
     private setInputText = async () => {
-        const text = await this.filterText(this.props[PropertyKey.kPropertyText]);
-        if (text.length > 0) {
-            this.inputElement.value = text;
-        }
+        this.inputElement.value = await this.filterText(this.props[PropertyKey.kPropertyText]);
     }
 
     public focus = () => {

js/apl-html/src/media/IMediaPlayerHandle.ts

@@ -16,6 +16,8 @@ export interface IMediaPlayerHandle extends IMediaEventListener {
 
     seek(offset: number): Promise<any>;
 
+    seekTo(position: number): Promise<any>;
+
     play(waitForFinish: boolean): Promise<any>;
 
     pause(): Promise<any>;

js/apl-html/src/media/MediaEventProcessor.ts

@@ -193,31 +193,15 @@ export function createMediaEventProcessor(mediaEventProcessorArgs: MediaEventPro
         },
         async seek({ seekOffset, fromEvent }): Promise<any> {
             await ensureLoaded.call(this, fromEvent);
-            const mediaResource: IMediaResource = this.playbackManager.getCurrent();
-            const mediaOffsetMs: number = mediaResource.offset;
             const currentPlaybackPositionMs: number = toMillisecondsFromSeconds(
                 this.player.getCurrentPlaybackPositionInSeconds()
             );
-            const desiredPlaybackPositionMs: number = currentPlaybackPositionMs + seekOffset;
-            const videoDurationMs = toMillisecondsFromSeconds(this.player.getDurationInSeconds());
-            const isNonDefaultDuration: boolean = mediaResource.duration > 0;
-            const isCurrentPositionOutOfBounds: boolean =
-                videoDurationMs <= desiredPlaybackPositionMs;
-
-            if (isCurrentPositionOutOfBounds) {
-                // minus unit time otherwise will rollover to start
-                if (isNonDefaultDuration) {
-                    this.player.setCurrentTimeInSeconds(mediaOffsetMs +
-                        toSecondsFromMilliseconds(mediaResource.duration) - 0.001);
-                } else {
-                    this.player.setCurrentTimeInSeconds(toSecondsFromMilliseconds(videoDurationMs) - 0.001);
-                }
-            } else if (desiredPlaybackPositionMs < mediaOffsetMs) {
-                this.player.setCurrentTimeInSeconds(toSecondsFromMilliseconds(mediaOffsetMs));
-            } else {
-                this.player.setCurrentTimeInSeconds(toSecondsFromMilliseconds(desiredPlaybackPositionMs));
-            }
-
+            setPlayerPosition(this.player, this.playbackManager.getCurrent(), currentPlaybackPositionMs + seekOffset);
+            this.updateMediaState(fromEvent);
+        },
+        async seekTo({ position, fromEvent }): Promise<any> {
+            await ensureLoaded.call(this, fromEvent);
+            setPlayerPosition(this.player, this.playbackManager.getCurrent(), position);
             this.updateMediaState(fromEvent);
         },
         async rewind({ fromEvent }): Promise<any> {
@@ -438,3 +422,27 @@ function ensureValidMediaState(mediaState: any): mediaState is APL.IMediaState {
 function isValidMediaStateValue(n: any): n is number {
     return !Number.isNaN(n) && n !== undefined;
 }
+
+function setPlayerPosition(player: any, mediaResource: IMediaResource, desiredPlaybackPositionMs: number) {
+    const mediaOffsetMs: number = mediaResource.offset;
+    const videoDurationMs = toMillisecondsFromSeconds(player.getDurationInSeconds());
+    const providedVideoDurationMs = mediaResource.duration;
+    const isDurationProvided: boolean = mediaResource.duration !== 0;
+
+    // minus unit time for EOF otherwise will rollover to start
+    const endOfFileMs = videoDurationMs - 1;
+    const endOfOffsetAndDurationMs = mediaOffsetMs + providedVideoDurationMs - 1;
+
+    // Calculate the range of the clipped track based on `offset` and `duration` values
+    const trueStart = Math.max(0, mediaOffsetMs);
+    const trueEnd = (isDurationProvided)
+            ? Math.min(endOfFileMs, endOfOffsetAndDurationMs)
+            : endOfFileMs;
+
+    player.setCurrentTimeInSeconds(toSecondsFromMilliseconds(
+        Math.min(
+            Math.max(desiredPlaybackPositionMs, trueStart),
+            trueEnd
+        )
+    ));
+}

js/apl-html/src/media/MediaEventSequencer.ts

@@ -14,6 +14,7 @@ export enum VideoInterface {
     PAUSE = 'pause',
     STOP = 'stop',
     SEEK = 'seek',
+    SEEKTO = 'seekTo',
     REWIND = 'rewind',
     PREVIOUS = 'previous',
     NEXT = 'next',

js/apl-html/src/media/MediaPlayerHandle.ts

@@ -74,6 +74,13 @@ export class MediaPlayerHandle implements IMediaPlayerHandle, IMediaEventListene
         });
     }
 
+    public async seekTo(position: number): Promise<any> {
+        this.eventSequencer.enqueueForProcessing(VideoInterface.SEEKTO, {
+            position,
+            fromEvent: true
+        });
+    }
+
     public async play(waitForFinish: boolean): Promise<any> {
         // Route through video component so can be override
         if (!this.videoComponent) {

js/apl-html/src/media/Resource.ts

@@ -63,6 +63,7 @@ export enum ControlMediaCommandName {
    PREVIOUS = 'previous',
    REWIND = 'rewind',
    SEEK = 'seek',
+   SEEKTO = 'seekTo',
    SETTRACK = 'setTrack'
 }