Painobar-helper/IMPLEMENTATION_GUIDE.md

Pianobar Helper - Implementation Guide

Overview

This document provides complete implementation details for the Pianobar Helper Windows Forms application.

Architecture

Core Components Created

1. ProfileManager.cs - Backend profile management system

   • Handles profile creation, deletion, and configuration
   • Stores profiles in JSON format in AppData
   • Generates Pianobar config files with credentials

2. PianobarManager.cs - Process lifecycle manager

   • Direct pianobar.exe process control
   • Real-time stdout/stdin communication
   • Song metadata parsing
   • Event-driven architecture

3. OutputManager.cs - Multi-output mechanism handler

   • Text file export
   • Local web server (JSON endpoint)
   • Windows Toast Notifications (placeholder)
   • Windows SMTC integration (placeholder)

4. MainForm (Main.cs) - Primary application interface

5. SettingsForm (Settings.cs) - Profile and configuration management

6. StationForm (StationForm.cs) - Station picker interface

Designer File Issues

The Designer files (.Designer.cs) need to be regenerated through Visual Studio's Form Designer. Here's what needs to be done:

MainForm Designer Controls Required

Open Main.cs in the Form Designer and add these controls:

MenuStrip (menuStrip1):

• fileToolStripMenuItem - "File" menu
  • settingsToolStripMenuItem - "Settings..." menu item
  • profilesToolStripMenuItem - "Profiles" submenu (dynamically populated)

StatusStrip (statusStrip1):

• statusLabelLeft (ToolStripStatusLabel) - Connection indicator
• statusLabelCenter (ToolStripStatusLabel) - Alternating profile/station info
• statusLabelRight (ToolStripStatusLabel) - Event feed

Buttons:

• connect_button - "Connect" button (wire to btnConnect_Click)
• disconnect_button - "Disconnect" button (wire to btnDisconnect_Click)
• stations_button - "Stations" button (wire to btnStations_Click)

GroupBox (groupBox1) - "Playback Controls":

• btnPlayPause - "Play / Pause" button (wire to btnPlayPause_Click)
• btnSkip - "Skip" button (wire to btnSkip_Click)

Additional Controls:

• album_art_picture_box (PictureBox) - For album art display
• info_table_Panel (TableLayoutPanel) - For song metadata display

SettingsForm Designer Controls Required

Open Settings.cs in the Form Designer and add these controls:

GroupBox (profiles_group_box) - "Profile Management":

• selected_profile_label - Label: "Selected profile:"
• profiles_combo_box_selector (ComboBox) - Profile selector (wire to profiles_combo_box_selector_SelectedIndexChanged)
• new_profile_button - "+ New" button (wire to new_profile_button_Click)
• delete_profile_button - "Delete" button (wire to delete_profile_button_Click)

GroupBox (profile_configuration_group_box) - "Profile Configuration":

TabControl (profile_config_tab_control):

Tab 1 (outputs_tab_page) - "Outputs":

• obs_text_output_check_box - "File output (For OBS / Streaming)"
• output_label - "Output Folder:"
• output_folder_text_box (TextBox)
• output_folder_browse_button - "Browse" (wire to output_folder_browse_button_Click)
• local_web_server_check_box - "Enable Local Web Server"
• port_label - "Port:"
• textBox1 (TextBox) - Port number input
• chk_toast_notifications - "Show Windows Toast Notifications"
• chkSMTC - "Windows System Media Controls (SMTC)"

Tab 2 (pianobar_override_tab_page) - "Pianobar Config & Auth":

• chkOverrideCredentials - "Enable Profile Credentials..." (wire to chkOverrideCredentials_CheckedChanged)
• txtConfigFilePathLabel - "Config Save Path:"
• txtConfigFilePath (TextBox)
• btnBrowseConfigFile - "Browse" (wire to btnBrowseConfigFile_Click)
• UsernameLabel - "Username / Email:"
• txtPianobarUser (TextBox)
• PasswordLabel - "Password:"
• txtPianobarPass (TextBox) - Set UseSystemPasswordChar = true

Dialog Buttons:

• Add OK/Cancel buttons and wire appropriately to btnSave_Click and btnCancel_Click

StationForm Designer Controls Required

Open StationForm.cs in the Form Designer and add these controls:

GroupBox (station_list_group_box) - "Available Stations":

• search_label - "Search:"
• textBox1 (TextBox) - Search box (wire to textBox1_TextChanged)
• lstStations (ListBox) - Station list

Buttons:

• refresh_button - "Refresh stations" (optional)
• btnSelectStation - "Select Station" (wire to btnSelectStation_Click)
• btnCancelStation - "Cancel" (wire to btnCancelStation_Click)

Quick Fix Steps

1. Rebuild Designer Files:

   • Open Visual Studio
   • Open each form (Main.cs, Settings.cs, StationForm.cs) in the Designer
   • Right-click the form surface ? "View Code"
   • Close and reopen the Designer view
   • This should regenerate the Designer files properly

2. Alternative - Manual Constructor Fix: If the Designer files are corrupted, you can temporarily comment out the constructors in the .cs files and let Visual Studio regenerate them.

3. Verify Event Wiring:

   • In the Designer, select each control
   • In Properties window, click the Events icon (lightning bolt)
   • Double-click the appropriate event (e.g., Click, TextChanged)
   • This will wire up the event handlers automatically

Usage Instructions

First Run

1. Launch the application
2. Go to File ? Settings
3. Create a new profile (click "+ New")
4. Configure output settings (text file, web server, etc.)
5. (Optional) Enable credential override and set Pianobar username/password
6. Click OK to save

Connecting to Pianobar

1. Ensure pianobar.exe is in your PATH or specify full path
2. Click "Connect" button
3. Status indicator will show:
   • ?? Red = Disconnected
   • ?? Green = Connected (no outputs active)
   • ?? Blue = Connected (outputs active)

Playback Control

• Use "Play / Pause" button to toggle playback
• Use "Skip" button to skip current track
• Click "Stations" to open station picker

Profile Switching

• Go to File ? Profiles
• Select a different profile (checkmark shows active)
• Reconnect to apply new profile settings

Technical Details

Status Bar Behavior

The center status zone alternates every 10 seconds between:

• Profile name display
• Current station display

Output Mechanisms

Text File Output:

• Writes song metadata to specified text file
• Updates on each song change
• Format: Title, Artist, Album, Album Art URL, Timestamp

Web Server:

• Starts HTTP listener on specified port
• Serves JSON at http://localhost:<port>/
• JSON structure: { title, artist, album, albumArtUrl, timestamp }

Toast Notifications & SMTC:

• Currently placeholder implementations
• Requires Windows SDK references to fully implement
• See TODO comments in OutputManager.cs

Pianobar Communication Protocol

The app listens for these patterns in Pianobar output:

• Song metadata: Lines containing "Title:", "Artist:", "Album:", "coverArt:"
• Playing indicator: |> prefix
• Paused indicator: || prefix
• Station selection: | Station "..."

Troubleshooting

"InitializeComponent does not exist"

• The Designer files need to be regenerated
• Open each form in the Designer view
• Save the forms to regenerate Designer code

"Pianobar is already running"

• Close existing Pianobar instances
• The app detects running processes to avoid conflicts

Config file not generated

• Ensure "Override Credentials" is checked
• Verify config file path is valid
• Check write permissions to the target directory

Web server won't start

• Check if port is already in use
• Try a different port number
• Run as administrator if using port < 1024

Future Enhancements

1. SMTC Integration:

   • Add reference to Windows.Media
   • Implement SystemMediaTransportControls
   • Handle media key events

2. Toast Notifications:

   • Add reference to Windows.UI.Notifications
   • Implement ToastNotificationManager
   • Create custom toast templates with album art

3. Album Art Display:

   • Download album art from URL
   • Display in album_art_picture_box
   • Cache images locally

4. Song Info Display:

   • Populate info_table_Panel with metadata
   • Show song progress
   • Display station info

File Structure

PainoBar Helper/
??? Main.cs                   # Main form implementation
??? Main.Designer.cs          # Main form designer (regenerate)
??? Settings.cs               # Settings form implementation
??? Settings.Designer.cs      # Settings designer (regenerate)
??? StationForm.cs           # Station picker implementation
??? StationForm.Designer.cs  # Station designer (regenerate)
??? ProfileManager.cs        # Profile management backend
??? PianobarManager.cs       # Pianobar process manager
??? OutputManager.cs         # Output mechanisms handler
??? Program.cs               # Application entry point
??? IMPLEMENTATION_GUIDE.md  # This file

Contact & Support

For issues or questions about this implementation, refer to the inline code comments or the method documentation in each class.

All public methods include XML documentation comments explaining their purpose and parameters.