SpotiOSC - Yeusepe/Yeusepes-Modules GitHub Wiki

SpotiOSC Module Documentation

Welcome to the detailed documentation for the SpotiOSC module. This guide explains everything you need to know—from setup and configuration to usage and troubleshooting. SpotiOSC integrates Spotify control into your OSC environment and now includes an advanced Inter-Device Communication (IDC) System for avatar-to-avatar data exchange within VRChat.

Table of Contents

  1. What is SpotiOSC?
  2. Features
  3. Installation
  4. Configuration
  5. Usage
  6. Security Considerations
  7. Troubleshooting
  8. Frequently Asked Questions (FAQ)

What is SpotiOSC?

SpotiOSC is a module designed to enable control of Spotify playback via OSC (Open Sound Control). It integrates with Spotify’s Web API to perform actions such as play, pause, skip, adjust volume, and more. In addition, SpotiOSC now incorporates an Inter-Device Communication (IDC) System that facilitates direct communication between avatars in VRChat using visual encoding/decoding techniques.

Features

OSC Playback Control

  • Play/Pause: Toggle Spotify playback.
  • NextTrack/PreviousTrack: Skip forward or backward through tracks.
  • ShuffleEnabled: Enable or disable shuffle mode.
  • RepeatMode: Set the desired repeat mode.
  • Volume: Adjust the playback volume (0–100).
  • PlaybackPosition: Set or update the playback position (in milliseconds).
  • CurrentTrackName & CurrentTrackArtist: Retrieve and display details of the currently playing track.
  • AvailableDevices: List available playback devices for Spotify.

Jam Session Management

  • WantJam: Signal your intention to join a jam session.
  • InAJam: Indicates whether you are currently in a jam session.
  • IsJamOwner: Shows if you are the owner of the current jam session.
  • Session Handling: Uses encoding/decoding utilities to manage session IDs and join tokens for a collaborative experience.

Spotify API Integration

  • Data Retrieval: Fetch top artists, playlists, current track details, and available devices through HTTP requests.
  • Playback Commands: Execute commands for starting playback, skipping tracks, pausing, and adjusting volume and repeat mode.

Token Management & Security

  • Secure Token Handling: Uses secure strings to manage access and client tokens.
  • Automatic Validation: Validates and refreshes tokens as needed.
  • Authentication: Provides a custom SignIn interface for user authentication.
  • Privacy Guarantee:
    Security Note: Your username and password are never saved. All sensitive credentials are used solely for token generation and validation, ensuring your data remains secure.

Player Event Subscription

  • Real-Time Updates: Subscribes to player events to update playback status and track details.
  • Event Deduplication: Implements deduplication mechanisms to prevent processing duplicate events.

Inter-Device Communication (IDC) System

  • Overview:
    The IDC system is a new feature released alongside SpotiOSC. It enables direct communication between avatars in VRChat, allowing data (such as session IDs or messages) to be sent and received via visual signals encoded into OSC parameters.
  • Components:
    • StringEncoder: Encodes text data (e.g., session IDs) into a series of OSC signals using a custom bitwise protocol with timed delays.
    • StringDecoder: Captures screen data to decode visual signals back into text. It supports debugging through saved images and detailed logging.
  • Usage:
    SpotiOSC leverages the IDC system for secure and efficient session handling and avatar-to-avatar communication, enhancing collaborative interactions in VRChat.

Installation

Step-by-Step Guide

  1. Download the Module:

    • Open your VRCOSC application and navigate to the Downloads tab.
    • Locate the Yeusepe's Module Repo.
    • Download the SpotiOSC module from the repository.

  2. Enable the Module:

    • Go to the Modules tab within VRCOSC.
    • Find SpotiOSC in the list and enable it.

  3. Verify Native Libraries:

    • The module relies on native libraries (e.g., libusb-1.0.dll and cvextern.dll). Ensure these are accessible in your system or module directory.

Configuration

Default Configuration

  • Out-of-the-Box Operation:
    SpotiOSC is designed to work without manual intervention. Once enabled, it automatically fetches and validates tokens, subscribes to player events, and initializes the necessary OSC parameters.
  • Auto-Detection:
    The module auto-detects the VRChat window for screen capture and manages session data with minimal user input.

Advanced Configuration (Optional)

  • Authentication Settings:
    • Open the Account Settings panel in VRCOSC.
    • Use the custom SignIn button to log in with your Spotify account. This step generates the necessary tokens.
  • Token Management:
    • If tokens are missing or invalid, SpotiOSC will attempt to refresh them automatically.
    • You can review token logs and validation messages in the debug console.
  • Custom Parameter Adjustments:
    • Advanced users can modify OSC parameters for specific use cases such as adjusting playback position or volume granularity.

Usage

Parameters and Commands

SpotiOSC provides several OSC parameters to control various aspects of Spotify playback and session management. Below is a comprehensive list:

Parameter Name Type Mode Description
SpotiOSC/Enabled bool Read/Write Sends (true) if the module is enabled, or (false) otherwise.
SpotiOSC/WantJam bool Read/Write Indicates your desire to join (true) or leave (false) a jam session.
SpotiOSC/InAJam bool Write Indicates whether the user is currently participating in a jam session (true/false).
SpotiOSC/IsJamOwner bool Write Indicates if the current user is the host (owner) of the jam session (true/false).
SpotiOSC/Error bool Write Indicates an error state when triggered (true).
SpotiOSC/Touching bool Read/Write Set true when two devices come into contact, used for IDC (Inter-Device Communication).
SpotiOSC/Play bool Read/Write Starts Spotify playback when set to true.
SpotiOSC/Pause bool Read/Write Pauses Spotify playback when set to true.
SpotiOSC/NextTrack bool Read Skips to the next track when set to true.
SpotiOSC/PreviousTrack bool Read Skips to the previous track when set to true.
SpotiOSC/ShuffleEnabled bool Read/Write Toggles shuffle mode (true=shuffle on, false=off).
SpotiOSC/SmartShuffle bool Read/Write Enables smart shuffle mode (true/false).
SpotiOSC/RepeatMode int Read/Write Sets repeat mode (0=Off, 1=Repeat Track, 2=Repeat Playlist).
SpotiOSC/Timestamp int Read/Write Current playback timestamp in milliseconds since UNIX epoch modulo integer range.
SpotiOSC/PlaybackPosition int Read/Write Current playback position within the track, in milliseconds.
SpotiOSC/IsPlaying bool Write Playback active state (true=playing, false=paused/stopped).
SpotiOSC/DeviceIsActive bool Read/Write Indicates whether the playback device is currently active (true/false).
SpotiOSC/DeviceIsPrivate bool Read/Write Indicates if device is in a private session (true=private).
SpotiOSC/DeviceIsRestricted bool Read/Write Indicates if playback on the device is restricted (true=restricted).
SpotiOSC/DeviceSupportsVolume bool Read/Write Whether the playback device supports volume control (true=supported).
SpotiOSC/DeviceVolumePercent int Read/Write Playback device volume percentage (0-100).
SpotiOSC/ContextType int Write Context type (0=playlist, -1=other).
SpotiOSC/DiscNumber int Write Disc number of the currently playing track.
SpotiOSC/TrackDurationMs int Write Duration of the current track in milliseconds.
SpotiOSC/IsExplicit bool Write Indicates if the current track has explicit content (true/false).
SpotiOSC/IsLocal bool Write Indicates if the current track is local (true) or streamed (false).
SpotiOSC/SongPopularity int Write Popularity rating of the song (0-100), where 100 is most popular.
SpotiOSC/TrackNumber int Write Track number on the album.
SpotiOSC/AlbumTotalTracks int Write Total number of tracks in the current album.
SpotiOSC/AlbumType int Write Type of album (0=Single, 1=Album, 2=Other).
SpotiOSC/DisallowPausing bool Write Indicates if pausing playback is disallowed (true=cannot pause).
SpotiOSC/DisallowResuming bool Write Indicates if resuming playback is disallowed (true=cannot resume).
SpotiOSC/DisallowSkippingPrev bool Write Indicates if skipping to previous track is disallowed (true).
SpotiOSC/JamParticipantCount int Write Current number of participants in a jam session.
SpotiOSC/SessionMaxMemberCount int Write Maximum allowed members in a jam session.
SpotiOSC/SessionIsOwner bool Write Indicates if the user is the jam session owner (true).
SpotiOSC/SessionIsListening bool Write Indicates if the user is currently listening in the jam session (true).
SpotiOSC/SessionIsControlling bool Write Indicates if the user has playback control in the jam session (true).
SpotiOSC/QueueOnlyMode bool Write Indicates if the jam session is queue-only (true).
SpotiOSC/HostIsGroup bool Write Indicates if the host device for the session is a group device (true).

Example Commands

  • To Start Playback:
    Send a true command to SpotiOSC/Play.

  • To Pause Playback:
    Send a true command to SpotiOSC/Pause.

  • To Skip to the Next Track:
    Trigger the SpotiOSC/NextTrack parameter with a true command.

  • To Adjust Volume:
    Send a numerical value (0–100) to the SpotiOSC/Volume parameter.

  • To Signal Jam Participation:

    • Set SpotiOSC/WantJam to true to indicate your interest in joining a jam.
    • The module will handle session requests and update SpotiOSC/InAJam accordingly.

Chatbox

Here’s the full breakdown from all the Variables, Events, and States provided:

Variables

Variable Name Description
TrackName Name of the currently playing track
TrackArtist Primary artist of the track
TrackDurationMs Duration of the track in milliseconds
DiscNumber Disc number of the track
IsExplicit Whether the track is explicit
Popularity Popularity of the track (0–100)
TrackNumber Track number on the album
TrackUri Spotify URI of the track
CurrentlyPlayingType Type of item being played (track, ad, etc.)
AlbumName Name of the album
AlbumArtworkUrl URL of the album artwork
AlbumType Album type (single, album, etc.)
AlbumReleaseDate Release date of the album
AlbumTotalTracks Total number of tracks on the album
ShuffleState Whether shuffle is enabled
SmartShuffle Whether smart shuffle is enabled
RepeatState Current repeat mode
Timestamp Playback timestamp
ProgressMs Progress in milliseconds
Artists Comma-separated list of all artists
DeviceId ID of the device playing music
DeviceName Name of the active device
IsActiveDevice Whether the device is active
VolumePercent Volume percentage of the active device
ContextExternalUrl Spotify URL of the current context
ContextHref Spotify API href of the current context
ContextType Type of context (e.g., playlist)
ContextUri URI of the current context
InAJam Whether the user is in a Jam

Events

Event Name Description
PlayEvent Fired when playback starts
PauseEvent Fired when playback is paused
TrackChangedEvent Fired when the track changes
VolumeEvent Fired when the volume changes
RepeatEvent Fired when repeat mode is changed
ShuffleEvent Fired when shuffle is toggled
JamEvent Fired when Jam status is updated

States

State Name Description
Playing_Jam_Explicit_Shuffle In a Jam, playing explicit track with shuffle
Playing_Jam_Explicit_NoShuffle In a Jam, explicit track, no shuffle
Playing_Jam_Clean_Shuffle In a Jam, clean track with shuffle
Playing_Jam_Clean_NoShuffle In a Jam, clean track, no shuffle
Paused_Jam In a Jam, music is paused
Playing_Explicit_Shuffle Not in a Jam, explicit track with shuffle
Playing_Explicit_NoShuffle Not in a Jam, explicit track, no shuffle
Playing_Clean_Shuffle Not in a Jam, clean track with shuffle
Playing_Clean_NoShuffle Not in a Jam, clean track, no shuffle
Paused_Normal Not in a Jam, music is paused

Let me know if you'd like a markdown table version of this or want to extract it into a CSV or something else!

Security Considerations

  • Token Handling:
    SpotiOSC uses secure strings to manage and store access tokens and client tokens. These tokens are validated and refreshed automatically as needed.
  • Privacy Assurance:
    Your sensitive information—such as your username and password—is never saved. They are only used transiently for token generation and are immediately cleared from memory.
  • Data Transmission:
    All communications with the Spotify API are conducted over secure HTTP connections.
  • Logging:
    Debug and error logs do not include sensitive credential information, ensuring your privacy is maintained.

Troubleshooting

Common Issues

  1. Module Not Responding:

    • Ensure that the module is enabled in VRCOSC.
    • Check the debug logs for error messages related to token validation or player event subscription.

  2. OSC Commands Not Working:

    • Confirm that your OSC setup is correctly configured.
    • Verify that the correct parameters are being used.
    • Restart both VRCOSC and Spotify if necessary.

  3. Authentication Problems:

    • Ensure you have entered your credentials correctly using the SignIn interface.
    • Check the logs for token refresh errors and consult the troubleshooting section if needed.
    • If you get stuck in the login process, it may be due to a Chrome-related issue. Open Task Manager, look for any process named "chrome test", and force-stop it. Then retry the SignIn process.

  4. Inter-Device Communication (IDC) Issues:

    • Ensure that both devices (avatars) are within the correct range and have compatible setups.
    • Use the debug logs provided by the IDC system (StringEncoder/StringDecoder) to diagnose issues with encoding or decoding.

Frequently Asked Questions (FAQ)

Do I need to configure anything manually?

For most users, SpotiOSC works out of the box. Advanced configuration is available if you encounter issues with token validation or if you wish to adjust specific OSC parameters.

What credentials are required?

You only need to sign in with your Spotify account via the provided SignIn interface. No usernames or passwords are stored, as they are solely used for token generation.

How do I know if the IDC system is working?

The IDC system logs detailed messages during encoding and decoding. Check the debug logs and saved images (if enabled) to confirm that data is being transmitted and received correctly.

Where can I get additional help?

If you encounter issues or have suggestions, please join our community on Discord!