🎵 VinylVerse Help & Documentation
🚀 Getting Started
1. Authentication
VinylVerse uses Auth0 for secure authentication. You'll be automatically redirected to log in with your preferred social account when you first visit.
2. Connect to Discogs
Important: You must connect your Discogs account to use VinylVerse features.
After logging in, click "Connect to Discogs" on your dashboard to authorize VinylVerse to access your collection data. This connection is secure and only accesses your public collection information.
3. Sync Your Collection
Once connected, click the "+ Collection" button to start syncing your Discogs collection. The initial sync runs through our comprehensive 8-step pipeline and may take several minutes depending on your collection size.
🔄 Data Processing Pipeline
Pipeline Overview: VinylVerse transforms raw Discogs collection data into intelligent, analyzable information through an 8-step processing pipeline with over 220 credit role mappings for comprehensive data standardization.
When you sync your collection, VinylVerse processes your Discogs data through a comprehensive pipeline. Each step transforms and enhances your music data:
🔗 Step 1: Collection Sync
What it does: Fetches your complete Discogs collection including folder organization, ratings, and custom notes.
Data processed: Basic album information, cover art, release IDs, folder assignments
Result: Local copy of your collection with Discogs metadata preserved
📀 Step 2: Release Details Sync
What it does: Retrieves detailed information for each release including full tracklists, credits, label information, and catalog numbers.
Data processed: Complete album metadata, track information, label details, format specifications
Result: Comprehensive release data stored as structured JSON for analysis
🎯 Step 3: Wantlist Sync
What it does: Synchronizes your Discogs wantlist with local database for AI recommendation analysis.
Data processed: Wantlist items, cover art, basic artist/album information
Result: Wantlist data available for AI-powered recommendations and analysis
⚙️ Step 4: Custom Fields Sync
What it does: Imports any custom field definitions you've created in Discogs (requires appropriate permissions).
Data processed: Custom field schemas, field types, available options
Result: Custom field structure preserved for future data enhancement
💰 Step 5: Collection Value Update
What it does: Calculates your collection's market value using real-time Discogs marketplace data.
Data processed: Market prices, collection value ranges, value history tracking
Result: Up-to-date collection valuation for portfolio tracking
👥 Step 6: Artist Extraction
What it does: Identifies and extracts all unique artists from your collection, creating a comprehensive artist database.
Data processed: Artist names, Discogs artist IDs, role information, collaboration data
Result: Normalized artist database with deduplication and relationship mapping
🎵 Step 7: Credit Extraction & Standardization
What it does: Processes all album and track credits through the role standardization system using our comprehensive credit_role_mappings database.
Data processed: Raw Discogs credits transformed using 220+ role mappings
Result: Clean, standardized credit data ready for network analysis and AI insights
🌐 Step 8: Network Generation
What it does: Creates pre-computed network visualization data showing artist collaborations and album connections.
Data processed: Artist relationships, collaboration networks, album credit networks
Result: High-performance network visualizations with sub-second loading times
🎯 Credit Role Standardization System
One of VinylVerse's most powerful features is its comprehensive credit role standardization system. This transforms chaotic, inconsistent Discogs role data into clean, analyzable information.
The Problem: Discogs Role Chaos
Example: A single artist might be credited as "Guitar", "Electric Guitar", "Guitar [Rhythm]", "Guitar, Vocals", "Guitarist", "Guitars", and "Lead Guitar" across different albums - making analysis impossible.
The Solution: Credit Role Standardization
VinylVerse uses a comprehensive credit_role_mappings database with over 220 standardization rules to transform chaotic Discogs data into clean, analyzable information.
🔄 Role Standardization Process
Raw Discogs Data Example:
• "Guitar, Vocals" → Multiple messy credits
• "Electric Guitar" → Inconsistent naming
• "Lead Vocals [Singer]" → Redundant descriptions
After VinylVerse Processing:
• "Guitar, Vocals" → Split into "Guitarist" + "Vocalist" (2 separate credits)
• "Electric Guitar" → Consolidated to "Guitarist"
• "Lead Vocals [Singer]" → Standardized to "Lead Vocalist"
🎯 Smart Processing Features
Compound Role Splitting: When Discogs lists "Guitar, Vocals", VinylVerse automatically creates separate credit entries for the same artist as both "Guitarist" and "Vocalist".
Smart Deduplication: Artists appear only once per role per album, and main artists don't get duplicate track listings.
🚀 Key Transformations
• Role Consolidation: 4,000+ role variations → 220 standardized roles
• Compound Splitting: "Guitar, Vocals" → 2 separate credit entries
• Artist Deduplication: Multiple spellings → Single artist entity
• Network Mapping: Individual credits → Collaboration relationships
🎵 Core Features - Complete Navigation Guide
🏠 Dashboard - Your Collection Command Center
Quick AI Chat Widget
Location: Top section of dashboard
What you can do:
• Context Dropdown: Click to select "No Context", "Full Collection", or "Wantlist" for AI responses
• Text Input: Type your music question directly
• Enter Key: Automatically navigates to AI Insights page with your question pre-loaded
• Auto-Submit: Question gets submitted immediately upon navigation for instant results
Collection Statistics Grid
Interactive Elements:
• Total Albums Card: Click to navigate to Collection page with all albums displayed
• Total Artists Card: Click to navigate to Collection page with artist filter active
• Average Rating Card: Click to navigate to Collection page sorted by rating
• Collection Value Card: Click to view detailed value breakdown and tracking history
• Top Genre Card: Click to navigate to Collection page filtered by your most common genre
• Recent Additions Card: Click to view your newest collection items with add dates
Navigation Bar
Always Available Elements:
• VinylVerse Logo: Click to return to Dashboard from any page
• Dashboard Link: Returns to main overview with refreshed statistics
• Collection Link: Opens full collection browser with filtering and search capabilities
• Wantlist Link: Opens wantlist manager with AI recommendation features
• AI Insights Link: Opens advanced AI chat interface with context modes
• Profile Link: Opens account management with subscription and token details
• Help Button: Opens this comprehensive help documentation
💿 Collection - Advanced Music Library Browser
Search and Filter Controls
Search Bar: Type artist names, album titles, or any metadata to find specific releases
Genre/Style Filter: Dropdown with all genres from your collection - click to filter by specific style
Folder Filter: Dropdown showing your Discogs folder organization - select to view specific folder contents
Combined Filtering: Use multiple filters simultaneously for precise collection browsing
Clear Filters Button: Reset all filters to view complete collection
Album Cards - Rich Interactive Elements
Album Cover: Click to open detailed album view with full tracklist and metadata
Album Title: Click to launch "Album Artists & Roles" tree visualization showing all contributors
Artist Name: Click to open artist-specific collection view filtered to that artist
Rating Display: Shows your Discogs rating (1-5 stars) with visual star indicators
Folder Badge: Shows which Discogs folder contains this album
Value Display: Current marketplace value range from Discogs pricing data
Generate AI Summary Button: Appears when album is selected - click for instant AI analysis using your tokens
Network Visualization Access
Collection Network Button: Opens interactive network showing artist collaborations across your collection
Album Credits Network Button: Opens focused network showing connections between albums through shared artists
Network Features: Zoom, pan, search highlighting, and connection exploration
Main Artist Highlighting: Red nodes indicate primary artists, blue nodes show contributors
Collection Management Actions
Add to Collection Button: Search Discogs releases and add new items to your collection
Sync Collection Button: Manually trigger pipeline sync to update from Discogs
Pipeline Status: Shows current processing step and completion percentage
Sort Options: Sort by date added, rating, artist name, or album title
View Toggle: Switch between grid view (covers) and list view (detailed metadata)
🎯 Wantlist - AI-Powered Wish List Manager
Wantlist Item Cards
Album Cover: Click to view detailed Discogs release information
Album Title: Click to launch wantlist-specific "Album Artists & Roles" visualization
Artist Name: Click to search your collection for other releases by this artist
Release Details: Year, label, catalog number with links to Discogs marketplace
Price Tracking: Current marketplace price range and availability status
Generate AI Summary Button: Instant AI analysis in wantlist context for purchase recommendations
AI Recommendation Engine
Wantlist Analysis Button: Triggers AI analysis of your entire wantlist for patterns and insights
Collection Gap Analysis: AI identifies missing albums that fit your collection patterns
Price Alert Setup: Set target prices for wantlist items with notification system
Similar Artist Discovery: AI suggests artists based on your wantlist patterns
Genre Expansion Suggestions: Recommendations for exploring related musical styles
Wantlist Management Tools
Add to Wantlist: Search and add releases directly from Discogs marketplace
Remove from Wantlist: Remove items with confirmation to prevent accidental deletions
Move to Collection: One-click move when you acquire a wantlist item
Sync Wantlist Button: Update from Discogs to reflect external changes
Export Options: Export wantlist data for external record keeping or sharing
🤖 AI Insights - Advanced Music Intelligence Interface
Context Mode Selector
No Context: General music chat without collection-specific information
Full Collection: AI has access to your complete collection data for personalized responses
Album Context: Focus AI responses on specific album when launched from collection cards
Wantlist Context: AI analyzes responses in context of your wantlist items and preferences
Search Context: AI provides information about searched artists or albums
Exploration Context: Deep-dive analysis mode for discovering music connections and patterns
Chat Interface Elements
Message Input: Type questions about music, your collection, or request recommendations
Send Button: Submit your question to Claude AI with current context applied
Stop Button: Interrupt AI response generation if needed
Thinking Indicator: Shows when AI is processing your request
Message History: Scroll through previous conversations in current context
Context Pills: Visual indicators showing which previous conversations belong to different contexts
Advanced AI Features
Web Search Integration: AI can search current music information and provide citations
Citation System: Numbered references [1], [2] with clickable source links
Token Usage Display: Real-time token consumption tracking for budget management
Response Formatting: Rich text with bold, italics, lists, and structured information
Conversation Continuity: AI remembers context across multiple questions in same session
Smart Prompts: Access pre-written prompts optimized for different music analysis tasks
Collection Search Integration
Artist Search: Search your collection for specific artists and launch AI analysis
Album Search: Find albums in your collection and get AI insights
Auto-Context Setting: Searches automatically set appropriate AI context
Quick Analysis: Generate instant summaries for searched items
Related Recommendations: AI suggests similar artists or albums from your collection
📊 Network Visualizations - Interactive Music Relationship Maps
Collection Network Visualization
Node Types:
• Red Nodes (Large): Main artists with white borders for easy identification
• Blue Nodes (Standard): Contributing artists and collaborators
• Album Thumbnails: Album cover images as connection points
Interactive Controls:
• Mouse Wheel: Zoom in/out to explore different network levels
• Click and Drag: Pan around large networks to explore all connections
• Node Hover: Tooltip shows artist name and role information
• Node Click: Highlights all connections for selected artist
• Search Bar: Type artist name to highlight their position in network
Album Credits Network
Three-Node Relationships: Albums → Artists → Albums showing collaboration patterns
Connection Filtering: Only shows meaningful creative relationships (excludes technical roles)
Degree of Separation: Explore how albums connect through shared artists
Network Constraints: Limited to 50 albums and 200 connections for optimal performance
Focus Mode: Click album to highlight all its artist connections and related albums
Tree Visualizations
Album Artists & Roles:
• Root Node: Album cover thumbnail at center
• Artist Branches: Lines connecting to all contributing artists
• Role Leaves: Specific roles (Guitarist, Vocalist, etc.) for each artist
• Expandable Nodes: Click to expand/collapse role details
• Role Grouping: Artists with multiple roles show consolidated view
Interactive Features:
• Node Spacing: Optimized layout prevents overlap in complex credits
• Text Limits: Artist names up to 40 characters, roles up to 30 characters
• Color Coding: Different colors for different role categories
👤 Profile - Account & Subscription Management Center
Account Information Section
User Profile Display: Shows your Auth0 account name and email
Account Creation Date: When you first signed up for VinylVerse
Last Login Information: Track your recent account activity
Account Settings Button: Access Auth0 account management (external link)
Privacy Settings: Control data sharing and collection preferences
Subscription Management
Current Plan Display: Shows "Pro Subscription" with $6.99/month pricing
Subscription Plan Button: Click to upgrade, change billing cycle, or manage subscription
Billing History: View past payments and download receipts
Payment Method: Update credit card information through secure Stripe interface
Cancellation Options: Self-service subscription cancellation with retention of purchased tokens
Token Balance & Usage Tracking
Token Breakdown Display:
• Free Tier Tokens: 30,000 one-time allocation for new users
• Monthly Tokens: 275,000 tokens included with Pro subscription (reset monthly)
• Purchased Tokens: Additional token packs bought separately (never expire)
• Total Available: Sum of all token types for easy budget tracking
Usage Analytics:
• Standard AI Features: Regular chat and on-demand summaries
• Batch AI Processing: Large-scale album/artist analysis with 50% discount
• Usage History: Track consumption patterns over time
• Cost Projections: Estimate monthly usage based on current patterns
Token Purchase Options
275K Token Pack: $6.99 for standard usage - equivalent to one month of Pro subscription
1.1M Token Pack: $19.99 for heavy usage - best value for large collections
Instant Processing: Purchased tokens available immediately after payment
Secure Checkout: Stripe-powered payment processing with saved payment methods
No Expiration: Purchased tokens never expire and remain available even after subscription cancellation
Discogs Integration Status
Connection Status: Shows "Connected to Discogs" with username display
OAuth Management: Reconnect or disconnect your Discogs account
Permission Scope: View granted permissions and revoke access if needed
Collection Sync Status: Last sync time and current pipeline progress
Data Privacy: Control what collection data is accessed and processed
Pipeline Processing Status
Current Step Display: Shows which of the 8 pipeline steps is currently processing
Progress Percentage: Real-time completion status for current step
Step Details: Explanation of what each pipeline step accomplishes
Processing Time Estimates: Expected completion time for remaining steps
Error Handling: Clear error messages with suggested solutions for pipeline issues
Manual Sync Button: Force collection re-sync if automatic sync encounters issues
🤖 AI Features & Token System
Context Modes
- No Context: General music discussion and recommendations
- Full Collection: Questions about your entire processed collection
- Album Context: Deep analysis of specific albums using standardized credits
- Wantlist: Recommendations based on your synchronized wantlist
Token System
VinylVerse uses a token-based system for AI features:
- Free Tier: 30,000 tokens to explore AI features
- Pro Subscription: $6.99/month for 275,000 tokens
- Token Packs: Additional tokens available for purchase
Batch Processing: Save 50% on tokens when using AI batch features for album and artist summaries using your standardized collection data.
Navigation
- Dashboard: Overview of your collection with quick AI chat
- Collection: Browse and search your synchronized albums
- Wantlist: View and manage your Discogs wantlist
- AI Insights: Advanced AI chat with context modes and prompts
- Profile: Manage your subscription, tokens, and account settings
🛠 Troubleshooting
Pipeline Processing Issues
Pipeline Stuck on Specific Step: Each pipeline step has built-in fault tolerance. If a step fails, the system will retry with exponential backoff. Check your profile for pipeline status updates.
Credit Standardization Issues: Our role mapping system covers 220+ common roles. Unmapped roles are preserved as-is and can be manually mapped through the admin interface.
Network Generation Problems: Network visualizations are pre-computed for performance. If networks appear empty, ensure Step 8 (Network Generation) completed successfully in your pipeline.
Common Issues
Discogs Connection Issues: If you can't connect to Discogs, try logging out of Discogs in another browser tab, then reconnect through VinylVerse.
Collection Not Syncing: Ensure your Discogs collection is public and you have granted the necessary permissions during OAuth.
AI Features Not Working: Check your token balance in your profile. If you're out of tokens, consider upgrading or purchasing a token pack.
🔒 Privacy & Security
- Data Encryption: All data encrypted in transit and at rest
- User Isolation: Complete data isolation between user accounts
- Processing Transparency: Full pipeline visibility and progress tracking
- Discogs Permissions: Only accesses public collection data with your explicit consent
- Data Retention: Processed data linked to your account for personalized insights
💡 Tips & Best Practices
Sync Regularly: Keep your collection synchronized to ensure AI insights reflect your latest additions and the pipeline processes new data.
- Use specific questions in AI chat for better responses
- Try different context modes to get varied perspectives
- Explore network visualizations to discover new connections
- Use batch processing for cost-effective AI analysis of large collections
- Organize your Discogs collection in folders for better filtering
- Monitor pipeline progress in your profile to track data processing
🔒 Privacy & Security
- Data Encryption: All data encrypted in transit and at rest
- User Isolation: Complete data isolation between user accounts
- Processing Transparency: Full pipeline visibility and progress tracking
- Discogs Permissions: Only accesses public collection data with your explicit consent
- Data Retention: Processed data linked to your account for personalized insights
💡 Tips & Best Practices
Sync Regularly: Keep your collection synchronized to ensure AI insights reflect your latest additions and the pipeline processes new data.
- Use specific questions in AI chat for better responses
- Try different context modes to get varied perspectives
- Explore network visualizations to discover new connections
- Use batch processing for cost-effective AI analysis of large collections
- Organize your Discogs collection in folders for better filtering
- Monitor pipeline progress in your profile to track data processing
Welcome to VinylVerse! Your Discogs collection data is now transformed into intelligent, analyzable information ready for AI-powered insights and advanced music discovery through our comprehensive 8-step pipeline.
← Back to VinylVerse
Last updated: June 28, 2025 - Comprehensive pipeline documentation with credit standardization details