How s4wa/soundcloud-status works
Project Type & Purpose
• The project is a streaming-related integration tool primarily aimed at streamers and gamers. Its purpose is to update or display a “SoundCloud Status” that integrates with Discord (using the pypresence library) and works in conjunction with streaming software like OBS.
• It is a hybrid system composed of a browser userscript (designed for Tampermonkey in Chrome) and a backend Python “server” process that handles configuration, exports data (such as artwork images and text exports), and updates Discord status.
Analyzing the File Structure
• Two main directories exist:
• The “chrome” folder contains the userscript (contents.user.js) used in Tampermonkey. This is the client-side part that runs within the browser on SoundCloud’s website.
• The “server” folder contains multiple Python scripts (main.py, exporter.py, reset.py), a configuration file (config.ini), and a settings utilities file (settings.py). There’s also a batch file (start.bat) for launching the Python server on Windows.
• The structure suggests a clear separation of concerns where the client-side script gathers or interacts with the webpage (SoundCloud) and the server-side Python application manages state, interacts with Discord via pypresence, and provides OBS with updated files (export.txt, artwork.jpg).
Key Insights from the README
• The README explains the intended usage: installing the Tampermonkey script, running the server, and then opening soundcloud.com.
• It details integration with Discord and OBS (for stream overlays) and points out that it works only on Windows.
• The external dependencies (pypresence, urllib3) hint at network communication and Discord API integration.
a. Main Components:
• Browser Component: “Tampermonkey Script (contents.user.js)” running in Chrome.
• Python Server: Contains core functionalities in main.py, exporter.py, reset.py, and uses config.ini/settings.py to control behavior.
• Discord Presence: Integrated via the pypresence library (as part of the server) to update Discord’s activity/status.
• OBS Integration: Uses exported files (artwork.jpg and export.txt) from the server as visual or textual sources to show the current SoundCloud status in OBS.
• External Service: SoundCloud (the website being operated upon to detect or extract song playback info).
b. Establish Relationships and Interactions:
• The Browser Component (userscript) monitors changes on SoundCloud’s website. It may collect current track and artwork details.
• It communicates (either via HTTP calls, WebSocket, or by direct file I/O – depending on the actual implementation in the server) with the Python Server. This communication channel is key, as it passes dynamic data (song info) to be processed.
• The Python Server processes the incoming data, updates relevant files (export.txt for textual status and artwork.jpg for images), and uses pypresence to update Discord’s status.
• OBS, as an external display tool, reads these exported files to overlay the current SoundCloud status on the streaming screen.
• Data flow from SoundCloud → Tampermonkey Script → Python Server → Discord and OBS export files.
• A feedback loop might also be illustrated if the server monitors for changes or re-exports new information.
c. Architectural Patterns/Design Principles:
• Separation of Concerns: Clear split between client (browser script) and server (Python application).
• Event-Driven Data Flow: The system is triggered by events (e.g., a new song playing on SoundCloud) which flow through the components.
• Modular Design: Even within the server, different scripts handle specific functionalities (e.g., exporter.py for file exports, reset.py for state resets).
• Extensibility: While the project is “discontinued,” the README suggests that users could swap in similar tools. Mark potential integration points (e.g., how the script connects with OBS or Discord) that allow for future changes.
d. Technologies, Frameworks, and Libraries:
• Python (version 3.7.4) as the main language for the backend.
• pypresence for Discord status updates.
• urllib3 for handling network communication.
• Tampermonkey (a Chrome extension) that uses JavaScript (contents.user.js) for client-side operations.
• OBS for streaming overlays reading exported files.