Merge pull request #17764 from mrdoob/audio

Audio: Refactored pause time code.

Author: mrdoob

docs/api/en/audio/Audio.html

@@ -85,14 +85,11 @@ <h3>[property:AudioListener listener]</h3>
 		<h3>[property:Number playbackRate]</h3>
 		<p>Speed of playback. Default is *1*.</p>
 
-		<h3>[property:Number startTime]</h3>
-		<p>The time at which the sound should begin to play. Same as the *when* paramter of [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/start AudioBufferSourceNode.start](). Default is *0*.</p>
-
 		<h3>[property:Number offset]</h3>
-		<p>An offset to the time within the audio buffer that playback should begin. Same as the *offset* paramter of [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/start AudioBufferSourceNode.start](). Default is *0*.</p>
+		<p>An offset to the time within the audio buffer that playback should begin. Same as the *offset* parameter of [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/start AudioBufferSourceNode.start](). Default is *0*.</p>
 
 		<h3>[property:Number duration]</h3>
-		<p>Overrides the duration of the audio. Same as the *duration* paramter of [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/start AudioBufferSourceNode.start](). Default is *undefined* to play the whole buffer.</p>
+		<p>Overrides the duration of the audio. Same as the *duration* parameter of [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/start AudioBufferSourceNode.start](). Default is *undefined* to play the whole buffer.</p>
 
 		<h3>[property:String source]</h3>
 		<p>An [link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode AudioBufferSourceNode] created
@@ -150,7 +147,7 @@ <h3>[method:Float getVolume]( value )</h3>
 		Return the current volume.
 		</p>
 
-		<h3>[method:Audio play]()</h3>
+		<h3>[method:Audio play]( delay )</h3>
 		<p>
 		If [page:Audio.hasPlaybackControl hasPlaybackControl] is true, starts playback.
 		</p>
@@ -162,7 +159,7 @@ <h3>[method:Audio pause]()</h3>
 
 		<h3>[method:null onEnded]()</h3>
 		<p>
-		Called automatically when playback finished. Sets If [page:Audio.isPlaying isPlaying] to false.
+		Called automatically when playback finished.
 		</p>
 
 		<h3>[method:Audio setBuffer]( audioBuffer )</h3>
@@ -229,8 +226,7 @@ <h3>[method:Audio setVolume]( [param:Float value] )</h3>
 
 		<h3>[method:Audio stop]()</h3>
 		<p>
-		If [page:Audio.hasPlaybackControl hasPlaybackControl] is enabled, stops playback,
-		resets [page:Audio.startTime startTime] to *0* and sets [page:Audio.isPlaying isPlaying] to false.
+		If [page:Audio.hasPlaybackControl hasPlaybackControl] is enabled, stops playback.
 		</p>
 
 		<h2>Source</h2>

docs/api/zh/audio/Audio.html

@@ -84,9 +84,6 @@ <h3>[property:Boolean isPlaying]</h3>
 		<h3>[property:AudioListener listener]</h3>
 		<p>A reference to the listener object of this audio.</p>
 
-		<h3>[property:Number startTime]</h3>
-		<p>开始播放的时间. 和[link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/start AudioBufferSourceNode.start]()的*when*参数一样. 默认为 *0*.</p>
-
 		<h3>[property:Number offset]</h3>
 		<p>音频开始播放的偏移时间. 和[link:https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/start AudioBufferSourceNode.start]()的*offset*参数一样. 默认为 *0*.</p>
 
@@ -146,7 +143,7 @@ <h3>[method:Float getVolume]( value )</h3>
 		返回音量.
 		</p>
 
-		<h3>[method:Audio play]()</h3>
+		<h3>[method:Audio play]( delay )</h3>
 		<p>
 		如果[page:Audio.hasPlaybackControl hasPlaybackControl]是true, 开始播放.
 		</p>
@@ -158,7 +155,7 @@ <h3>[method:Audio pause]()</h3>
 
 		<h3>[method:null onEnded]()</h3>
 		<p>
-		播放完成后自动调用. 如果[page:Audio.isPlaying isPlaying]设置为false.
+		播放完成后自动调用.
 		</p>
 
 		<h3>[method:Audio setBuffer]( audioBuffer )</h3>
@@ -220,8 +217,7 @@ <h3>[method:Audio setVolume]( [param:Float value] )</h3>
 
 		<h3>[method:Audio stop]()</h3>
 		<p>
-		如果[page:Audio.hasPlaybackControl hasPlaybackControl]是true, 停止播放,
-		重新设置[page:Audio.startTime startTime]为 *0* 和 设置 [page:Audio.isPlaying isPlaying]为false.
+		如果[page:Audio.hasPlaybackControl hasPlaybackControl]是true, 停止播放.
 		</p>
 
 		<h2>源码</h2>

src/Three.Legacy.js

@@ -1918,19 +1918,32 @@ Object.defineProperties( WebVRManager.prototype, {
 
 //
 
-Audio.prototype.load = function ( file ) {
+Object.defineProperties( Audio.prototype, {
 
-	console.warn( 'THREE.Audio: .load has been deprecated. Use THREE.AudioLoader instead.' );
-	var scope = this;
-	var audioLoader = new AudioLoader();
-	audioLoader.load( file, function ( buffer ) {
+	load: {
+		value: function ( file ) {
 
-		scope.setBuffer( buffer );
+			console.warn( 'THREE.Audio: .load has been deprecated. Use THREE.AudioLoader instead.' );
+			var scope = this;
+			var audioLoader = new AudioLoader();
+			audioLoader.load( file, function ( buffer ) {
 
-	} );
-	return this;
+				scope.setBuffer( buffer );
 
-};
+			} );
+			return this;
+
+		}
+	},
+	startTime: {
+		set: function () {
+
+			console.warn( 'THREE.Audio: .startTime is now .play( delay ).' );
+
+		}
+	}
+
+} );
 
 AudioAnalyser.prototype.getData = function () {
 

src/audio/Audio.d.ts

@@ -15,7 +15,6 @@ export class Audio extends Object3D {
 	buffer: null | Audio;
 	detune: number;
 	loop: boolean;
-	startTime: number;
 	offset: number;
 	duration: number | undefined;
 	playbackRate: number;
@@ -30,7 +29,7 @@ export class Audio extends Object3D {
 	setMediaElementSource( mediaElement: HTMLMediaElement ): this;
 	setMediaStreamSource( mediaStream: MediaStream ): this;
 	setBuffer( audioBuffer: AudioBuffer ): this;
-	play(): this;
+	play( delay?: number ): this;
 	onEnded(): void;
 	pause(): this;
 	stop(): this;

src/audio/Audio.js

@@ -24,14 +24,16 @@ function Audio( listener ) {
 	this.loop = false;
 	this.loopStart = 0;
 	this.loopEnd = 0;
-	this.startTime = 0;
 	this.offset = 0;
 	this.duration = undefined;
 	this.playbackRate = 1;
 	this.isPlaying = false;
 	this.hasPlaybackControl = true;
 	this.sourceType = 'empty';
 
+	this._startedAt = 0;
+	this._pausedAt = 0;
+
 	this.filters = [];
 
 }
@@ -90,7 +92,9 @@ Audio.prototype = Object.assign( Object.create( Object3D.prototype ), {
 
 	},
 
-	play: function () {
+	play: function ( delay ) {
+
+		if ( delay === undefined ) delay = 0;
 
 		if ( this.isPlaying === true ) {
 
@@ -106,15 +110,15 @@ Audio.prototype = Object.assign( Object.create( Object3D.prototype ), {
 
 		}
 
-		var source = this.context.createBufferSource();
+		this._startedAt = this.context.currentTime + delay;
 
+		var source = this.context.createBufferSource();
 		source.buffer = this.buffer;
 		source.loop = this.loop;
 		source.loopStart = this.loopStart;
 		source.loopEnd = this.loopEnd;
 		source.onended = this.onEnded.bind( this );
-		this.startTime = this.context.currentTime;
-		source.start( this.startTime, this.offset, this.duration );
+		source.start( this._startedAt, this._pausedAt + this.offset, this.duration );
 
 		this.isPlaying = true;
 
@@ -138,9 +142,11 @@ Audio.prototype = Object.assign( Object.create( Object3D.prototype ), {
 
 		if ( this.isPlaying === true ) {
 
+			this._pausedAt = ( this.context.currentTime - this._startedAt ) * this.playbackRate;
+
 			this.source.stop();
 			this.source.onended = null;
-			this.offset += ( this.context.currentTime - this.startTime ) * this.playbackRate;
+
 			this.isPlaying = false;
 
 		}
@@ -158,9 +164,10 @@ Audio.prototype = Object.assign( Object.create( Object3D.prototype ), {
 
 		}
 
+		this._pausedAt = 0;
+
 		this.source.stop();
 		this.source.onended = null;
-		this.offset = 0;
 		this.isPlaying = false;
 
 		return this;