Recording a session

[0x213F]

Abstract

A user should be able to record a listening session. For example, take the following broken down listening session. Everything bolded is a part of the new feature:

• Start playing my favorite album "FOOBAR."
• Record some text comments and voice recordings over "FOOBAR."
• "FOOBAR" finishes.
• Press record button.
• Record a voice over talking about "FOOBAR."
• Start playing "FOOBAR."
• The text comments and voice recordings from last time show up
• New text comments and voice recordings may be added.
• Other tracks or collections may be added to the queue.
• Common stream operations (play, pause, next, scanning) may be used. "Previous track" may not be used.
• Press stop recording button.
• Component appears presenting form to save/ discard recorded session.

Implementation

Step by step guide on implementation approach.

Preliminary groundwork

Basic changes to existing setup without changing functionality.

Schema

Here is the UML Diagram at the time of writing this (19/01/2021).

Here will be the changes to existing models:

• TextComment
  • track will need to be nullable.
  • session will need to be added (see Session table later in this document).
  • timestamp_ms is relative to session.started_at when Q(track__isnull=True) & Q(session__isnull=True).
  • Note: enforce that session xor track should be null.
• VoiceRecording
  • track will need to be nullable.
  • session will need to be added (see Session table later in this document).
  • timestamp_ms is relative to session.started_at when Q(track__isnull=True) & Q(session__isnull=True).
  • Note: enforce that session xor track should be null.

Stream operations

The stream operation endpoints streams:stream-next-track must be modified to expect an additional URL parameter:

• manuallyTriggered: a boolean value signifying wether the user manually triggered the "next track" action. The value will be False when the next track in the queue is auto-played.

Functional groundwork

Schema

New models (and respective admins) will be created:

• Session
  • meta
    • pghistory
  • fields
    • uuid
    • stream
    • began_at
    • finished_at
    • name
    • published_at
    • created_at
    • updated_at
    • deleted_at
• SessionRelatedObject
  • fields
    • comment
    • voice_recording
    • stream_operation
    • created_at
    • updated_at
    • deleted_at
• SessionOperation
  • fields
    • session
    • slug
    • data
    • timestamp_ms
    • created_at

Modify existing API endpoints

Disallow modification of "display historical text comments/ voice recordings" user settings value if there is an active recording session.

Functional implementation

New API endpoints

Create the following endpoints:

• streams:session-begin-recording
  • From the request, infer the user and stream and create a session.
  • Pass a parameter representing the user's preference. Either start the recording immediately (if nothing is currently playing) or at the start of the next track.
• streams:session-finish-recording
  • From the request and stream, infer the session and finish it.
  • Gather all text comments and voice recordings created from the session.
    • Created within the (began_at, finished_at) bounds.
    • If user settings permits, historical objects.
    • Create SessionRelatedObject for each object.
    • Set published_at or deleted_at.

Modify existing API endpoints

Create a new SessionOperation object inside each of the following endpoints (if there is an active session):

• streams:stream-play
• streams:stream-pause
• streams:stream-next-track
• streams:stream-scan-backward
• streams:stream-scan-forward

Inside streams:stream-next-track, if a session has been initialized but has not began (because the session was setup under the option "start recording on next track"), then begin the session.

Front-end

The rest of the implementation needs to happen on the front-end. More on that in a JR React issue: 0x213F/jukebox-radio-react#4

Questions and answers

Q: Where are the queue objects being tracked?

A: Queue objects are not being tracked. Only playback is tracked. So if you queue up 2 albums but the session only records the first album, the second album is nowhere inside the recorded session. Inside the session, let us assume something is added to the queue and then removed before it is played. It will not show up in the session anywhere.

Q: If queue objects are not tracked, then how does the session know what to play?

A: From the SessionOperation objects created inside the stream operation endpoint streams:stream-next-track.

Q: Why is the user settings for "display historic objects" disabled inside an active session?

A: When ending a session, it will be easier to determine what text comments/ voice recordings to attach to the session. If the value is toggled in the middle of a session, it just complicates things.

Q: Why is the stream operation "previous track" prohibited inside a session?

A: Due to the current architecture, there will be a bug if we allow "previous track" to happen inside a session. Here are the steps anticipated for the bug:

• Queue up a track with specified queue intervals (name might change to queue snippets).
• Play the track with specified queue intervals
• Once the track terminates, hit "previous track" twice.
• Edit the queue intervals for the next track (same as first point).
• Play the next track with revised intervals.
• BUG: recording is corrupt