add: fading configuration and processing for audio playback

Author: 1Lucas1apk

config.default.js

@@ -374,7 +374,35 @@ export default {
   audio: {
     quality: 'high', // high, medium, low, lowest
     encryption: 'aead_aes256_gcm_rtpsize',
-    resamplingQuality: 'best' // best, medium, fastest, zero order holder, linear
+    resamplingQuality: 'best', // best, medium, fastest, zero order holder, linear
+    fading: {
+      enabled: false,
+      // curve meanings:
+      // linear = constant rate, exponential = slow start then faster,
+      // logarithmic = fast start then slower, s-curve = smooth start/end
+      trackStart: {
+        duration: 0,
+        curve: 'linear'
+      },
+      trackEnd: {
+        duration: 0,
+        curve: 'linear'
+      },
+      trackStop: {
+        duration: 0,
+        curve: 'linear'
+      },
+      seek: {
+        duration: 0,
+        curve: 'linear'
+      },
+      ducking: {
+        enabled: false,
+        duration: 0,
+        targetVolume: 0.3,
+        curve: 'linear'
+      }
+    }
   },
   voiceReceive: {
     enabled: false,

src/api/sessions.id.players.js

@@ -30,6 +30,7 @@ const updatePlayerSchema = myzod
     volume: myzod.number().min(0).max(1000).optional(),
     paused: myzod.boolean().optional(),
     filters: filtersSchema.optional(),
+    fading: myzod.unknown().optional(),
     voice: voiceStateSchema.optional(),
     guildId: myzod.string().optional()
   })
@@ -52,6 +53,59 @@ const pathSchema = myzod.object({
     .optional()
 })
 
+const sanitizeFadingConfig = (raw) => {
+  const safe = {
+    enabled: false,
+    trackStart: { duration: 0, curve: 'linear' },
+    trackEnd: { duration: 0, curve: 'linear' },
+    trackStop: { duration: 0, curve: 'linear' },
+    seek: { duration: 0, curve: 'linear' },
+    ducking: {
+      enabled: false,
+      duration: 0,
+      targetVolume: 0.3,
+      curve: 'linear'
+    }
+  }
+
+  if (!raw || typeof raw !== 'object') return safe
+  safe.enabled = raw.enabled === true
+
+  const updateSection = (key) => {
+    const section = raw[key]
+    if (!section || typeof section !== 'object') return
+    if (Number.isFinite(section.duration)) {
+      safe[key].duration = Math.max(0, section.duration)
+    }
+    if (typeof section.curve === 'string') {
+      safe[key].curve = section.curve
+    }
+  }
+
+  updateSection('trackStart')
+  updateSection('trackEnd')
+  updateSection('trackStop')
+  updateSection('seek')
+
+  if (raw.ducking && typeof raw.ducking === 'object') {
+    safe.ducking.enabled = raw.ducking.enabled === true
+    if (Number.isFinite(raw.ducking.duration)) {
+      safe.ducking.duration = Math.max(0, raw.ducking.duration)
+    }
+    if (Number.isFinite(raw.ducking.targetVolume)) {
+      safe.ducking.targetVolume = Math.max(
+        0,
+        Math.min(1, raw.ducking.targetVolume)
+      )
+    }
+    if (typeof raw.ducking.curve === 'string') {
+      safe.ducking.curve = raw.ducking.curve
+    }
+  }
+
+  return safe
+}
+
 async function handler(nodelink, req, res, sendResponse, parsedUrl) {
   const parts = parsedUrl.pathname.split('/')
   const pathParams = {
@@ -426,6 +480,16 @@ async function handler(nodelink, req, res, sendResponse, parsedUrl) {
           await session.players.setFilters(guildId, payload)
         }
 
+        if (payload.fading !== undefined) {
+          logger(
+            'debug',
+            'PlayerUpdate',
+            `Setting fading for guild ${guildId}`
+          )
+          const sanitizedFading = sanitizeFadingConfig(payload.fading)
+          await session.players.setFading(guildId, sanitizedFading)
+        }
+
         const playerJson = await session.players.toJSON(guildId)
         return sendResponse(req, res, playerJson, 200)
       }

src/managers/playerManager.js

@@ -341,6 +341,41 @@ export default class PlayerManager {
     return player.setFilters(filtersPayload)
   }
 
+  async setFading(guildId, fadingConfig) {
+    const interception = await this._runInterceptors(
+      'setFading',
+      guildId,
+      fadingConfig
+    )
+    if (interception?.handled) return interception.result
+
+    const session = this.nodelink.sessions.get(this.sessionId)
+    const playerKey = `${this.sessionId}:${guildId}`
+
+    if (this.isCluster) {
+      const worker = this.nodelink.workerManager.getWorkerForGuild(playerKey)
+      if (!worker) throw new Error('Player not assigned to a worker.')
+      const result = await this.nodelink.workerManager.execute(
+        worker,
+        'playerCommand',
+        {
+          sessionId: this.sessionId,
+          guildId,
+          userId: session.userId,
+          command: 'setFading',
+          args: [fadingConfig]
+        }
+      )
+      if (result?.playerNotFound) {
+        throw new Error('Player not found.')
+      }
+      return result
+    }
+    const player = this.players.get(playerKey)
+    if (!player) throw new Error('Player not found locally.')
+    return player.setFading(fadingConfig)
+  }
+
   async updateVoice(guildId, voicePayload) {
     const interception = await this._runInterceptors(
       'updateVoice',

src/playback/player.js

@@ -47,6 +47,10 @@ export class Player {
     this.lastManualReconnect = 0
     this.audioMixer = null
     this._initAudioMixer()
+    this.fading = this.nodelink.options?.audio?.fading
+    this._fadeTimers = { trackEnd: null, pause: null, stop: null }
+    this._isResuming = false
+    this._pendingTrackStartFade = false
 
     this.isLyricsSubscribed = false
     this.currentLyrics = null
@@ -292,6 +296,7 @@ export class Player {
       this.isPaused = false
 
       if (!wasResuming && !this._isRestoring) {
+        this._fading('trackStart')
         this._emitTrackStart()
       }
     } else if (state.status === 'paused') {
@@ -391,6 +396,7 @@ export class Player {
     this.position = 0
     this.currentLyrics = null
     this.lyricsLineIndex = -1
+    this._fading('reset')
   }
 
   async _emitTrackStart() {
@@ -720,6 +726,8 @@ export class Player {
     if (this.volumePercent !== 100) {
       resource.setVolume(this.volumePercent / 100)
     }
+    this._fading('trackStartArm', { resource })
+    this._fading('trackEndSchedule', { startPosition: startTime || 0 })
 
     this.setFilters(this.filters)
 
@@ -775,6 +783,7 @@ export class Player {
         }
 
         this.track = { encoded, info, endTime, userData, audioTrackId }
+        this._fading('reset')
 
         if (!this.voice.endpoint || !this.voice.token) {
           logger(
@@ -897,6 +906,8 @@ export class Player {
       if (result) {
         this.emitEvent(GatewayEvents.SEEK, { position: this.position })
         if (this.isLyricsSubscribed) this._recalculateLyricsIndex()
+        this._fading('seek')
+        this._fading('trackEndSchedule', { startPosition: this.position })
       }
       return result
     } finally {
@@ -975,6 +986,7 @@ export class Player {
     if (this.volumePercent !== 100) {
       resource.setVolume(this.volumePercent / 100)
     }
+    this._fading('seekPrepare', { resource })
 
     this.setFilters(this.filters)
 
@@ -1032,6 +1044,7 @@ export class Player {
       if (this.volumePercent !== 100) {
         resource.setVolume(this.volumePercent / 100)
       }
+      this._fading('seekPrepare', { resource })
       resource.setFilters(this.filters)
 
       const oldStream = this.connection.play(resource)
@@ -1140,6 +1153,7 @@ export class Player {
     if (this.volumePercent !== 100) {
       resource.setVolume(this.volumePercent / 100)
     }
+    this._fading('seekPrepare', { resource })
 
     this.setFilters(this.filters)
 
@@ -1160,6 +1174,7 @@ export class Player {
       if (this.destroying || !this.track) return false
       if (this.connection && this.connStatus !== 'destroyed') {
         if (this.connection.audioStream) {
+          if (this._fading('trackStop')) return true
           this.connection.stop(EndReasons.STOPPED)
         } else {
           this._emitTrackEnd(EndReasons.STOPPED)
@@ -1211,6 +1226,11 @@ export class Player {
     return true
   }
 
+  setFading(config) {
+    this.fading = config
+    return true
+  }
+
   setFilters(filters) {
     if (this.destroying || !this.track) return false
     logger(
@@ -1553,6 +1573,7 @@ export class Player {
       guildId: this.guildId,
       track: this.track,
       volume: this.volumePercent,
+      fading: this.fading,
       paused: this.isPaused,
       filters: this.filters,
       state: {
@@ -1564,4 +1585,118 @@ export class Player {
       voice: { ...this.voice }
     }
   }
+
+  _fading(action, payload = {}) {
+    const timers = this._fadeTimers
+    if (!timers) return false
+
+    if (action === 'reset') {
+      if (timers.trackEnd) clearTimeout(timers.trackEnd)
+      if (timers.pause) clearTimeout(timers.pause)
+      if (timers.stop) clearTimeout(timers.stop)
+      timers.trackEnd = null
+      timers.pause = null
+      timers.stop = null
+      this._pendingTrackStartFade = false
+      return false
+    }
+
+    if (action === 'trackEndSchedule' && timers.trackEnd) {
+      clearTimeout(timers.trackEnd)
+      timers.trackEnd = null
+    }
+
+    if (!this.fading || this.fading.enabled !== true) return false
+
+    let section = null
+    if (action === 'trackStart' || action === 'trackStartArm')
+      section = this.fading.trackStart
+    else if (action === 'trackEndSchedule') section = this.fading.trackEnd
+    else if (action === 'trackStop') section = this.fading.trackStop
+    else if (action === 'seek') section = this.fading.seek
+    else if (action === 'seekPrepare') section = this.fading.seek
+    else return false
+
+    if (
+      !section ||
+      !Number.isFinite(section.duration) ||
+      section.duration <= 0
+    )
+      return false
+
+    if (action === 'trackStartArm') {
+      const resource = payload.resource
+      if (!resource?.setFadeVolume) return false
+      resource.setFadeVolume(0)
+      this._pendingTrackStartFade = true
+      return true
+    }
+
+    if (action === 'trackStart') {
+      if (!this._pendingTrackStartFade) return false
+      const stream = payload.resource || this.connection?.audioStream
+      if (!stream?.fadeTo) return false
+      this._pendingTrackStartFade = false
+      stream.fadeTo(1, section.duration, section.curve)
+      return true
+    }
+
+    if (action === 'seekPrepare') {
+      const resource = payload.resource
+      if (!resource?.setFadeVolume) return false
+      resource.setFadeVolume(0)
+      return true
+    }
+
+    if (action === 'seek') {
+      const stream = this.connection?.audioStream
+      if (!stream?.setFadeVolume) return false
+      stream.setFadeVolume(0)
+      stream.fadeTo(1, section.duration, section.curve)
+      return true
+    }
+
+    if (action === 'trackStop') {
+      const stream = this.connection?.audioStream
+      if (!stream?.fadeTo) return false
+      if (timers.stop) clearTimeout(timers.stop)
+      stream.fadeTo(0, section.duration, section.curve)
+      timers.stop = setTimeout(() => {
+        this.connection?.stop(EndReasons.STOPPED)
+        if (timers.stop) {
+          clearTimeout(timers.stop)
+          timers.stop = null
+        }
+      }, section.duration)
+      return true
+    }
+
+    if (action === 'trackEndSchedule') {
+      if (!this.track?.info) return false
+      const total =
+        this.track.endTime && this.track.endTime > 0
+          ? this.track.endTime
+          : this.track.info.length || 0
+      if (!Number.isFinite(total) || total <= 0) return false
+
+      const startPosition = payload.startPosition || 0
+      const remaining = Math.max(0, total - startPosition)
+      const fadeDuration = Math.min(section.duration, remaining)
+      const delay = Math.max(0, remaining - fadeDuration)
+
+      timers.trackEnd = setTimeout(() => {
+        const stream = this.connection?.audioStream
+        if (stream?.fadeTo) {
+          stream.fadeTo(0, fadeDuration, section.curve)
+        }
+        if (timers.trackEnd) {
+          clearTimeout(timers.trackEnd)
+          timers.trackEnd = null
+        }
+      }, delay)
+      return true
+    }
+
+    return false
+  }
 }