aherobo/viral_velocity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e559238be54c792f88ee2debf6a9212b40540997
viral_velocity/README.md
T
Aherobo Ovie Victor e559238be5 Initial commit
2025-10-27 18:43:42 +01:00

9.4 KiB
Raw Blame History

Viral Velocity - AI-Powered Social Media Image Scorer

🚀 Viral Velocity is an AI-powered mobile application that helps users optimize their social media posts by providing intelligent image scoring and enhancement recommendations.

🎯 What We Built

We've created a personalized 4-pillar scoring system using OpenAI GPT-4 Vision that analyzes images for:

  1. Technical Quality (25% weight) - Sharpness, resolution, noise, dynamic range, color fidelity
  2. Compositional Strength (25% weight) - Rule of thirds, leading lines, balance, depth, subject isolation
  3. Psychological Engagement (30% weight) - Face detection, emotional resonance, color psychology, storytelling
  4. Trend & Zeitgeist (20% weight) - Personalized aesthetic alignment based on user preferences

🌟 Key Feature: Personalization

The system now supports user preferences for personalized scoring:

  • Aesthetic: Y2K, Maximalist, Minimalist, Vintage, etc.
  • Niche: Fashion Influencer, Food Blogger, Business Professional, etc.
  • Target Audience: Gen Z, Millennials, Professionals, etc.
  • Content Type: Instagram Post, LinkedIn Post, TikTok, etc.
  • Brand Voice: Playful, Professional, Casual, etc.

🛠️ Setup Instructions

1. Install Dependencies

pip install -r requirements.txt

2. Get OpenAI API Key

  1. Go to OpenAI Platform
  2. Create a new API key
  3. Copy the key

3. Set Up Environment

Create a .env file in the project root:

OPENAI_API_KEY=your_actual_api_key_here

🚀 How to Use

Option 1: Run the API Server

python api.py

The API will be available at http://localhost:5300

Logs will be saved to:

  • viral_velocity.log - Main scorer logs

Available Endpoints:

  • GET / - API info
  • POST /score-image - Score an image with base64 data and optional user preferences
  • GET /health - Health check
  • GET /scoring-weights - View current scoring weights
  • GET /available-preferences - Get all available preference options

Option 2: Test with Sample Image

  1. Place a test image named test_image.jpg in the project directory
  2. Run the test script:
python test_scorer.py

Option 3: Test Personalized Scoring

python test_personalized.py

This will test the system with different user preferences and show how personalization affects scores.

Option 4: Use the Web Frontend

# Start the API server (serves both API and frontend)
python api.py

Then open http://localhost:5300 in your browser for a beautiful web interface!

Option 5: View Logs in Real-Time

python view_logs.py

This will show you detailed logs of what's happening during the scoring process.

Option 6: Use the API

import requests
import base64

# Encode image to base64
with open("image.jpg", "rb") as image_file:
    encoded_image = base64.b64encode(image_file.read()).decode()

# Prepare request
request_data = {
    "image": encoded_image,
    "user_preferences": {
        "aesthetic": "Y2K",
        "niche": "Fashion Influencer", 
        "target_audience": "Gen Z",
        "content_type": "Instagram Post",
        "brand_voice": "Playful and Trendy"
    }
}

# Send request
response = requests.post("http://localhost:5300/score-image", json=request_data)
result = response.json()

# Get the final score
print(f"Viral Score: {result['final_score']}/100")

# Get detailed breakdown
print(f"Technical Quality: {result['technical_quality']['score']}/100")
print(f"Compositional Strength: {result['compositional_strength']['score']}/100")
print(f"Psychological Engagement: {result['psychological_engagement']['score']}/100")
print(f"Trend & Zeitgeist: {result['trend_zeitgeist']['score']}/100")

Option 7: Use in Your Code (Direct)

from viral_velocity_scorer import ViralVelocityScorer

# Initialize scorer
scorer = ViralVelocityScorer()

# Analyze an image with personalized preferences
user_preferences = {
    "aesthetic": "Y2K",
    "niche": "Fashion Influencer", 
    "target_audience": "Gen Z",
    "content_type": "Instagram Post",
    "brand_voice": "Playful and Trendy"
}

# Analyze an image
result = scorer.analyze_image_efficient("path/to/your/image.jpg", user_preferences)

# Get the final score
print(f"Viral Score: {result['final_score']}/100")

# Get detailed breakdown
print(f"Technical Quality: {result['technical_quality']['score']}/100")
print(f"Compositional Strength: {result['compositional_strength']['score']}/100")
print(f"Psychological Engagement: {result['psychological_engagement']['score']}/100")
print(f"Trend & Zeitgeist: {result['trend_zeitgeist']['score']}/100")

# Check if preferences were used
print(f"Preferences used: {result['user_preferences_used']}")

📊 Sample Output

Generic Scoring (No Preferences)

{
  "final_score": 78.5,
  "technical_quality": {
    "score": 85,
    "weight": 0.25,
    "details": "Image shows good sharpness and color balance..."
  },
  "compositional_strength": {
    "score": 72,
    "weight": 0.25,
    "details": "Subject is well-positioned but could benefit from..."
  },
  "psychological_engagement": {
    "score": 82,
    "weight": 0.30,
    "details": "Strong emotional appeal with engaging facial expressions..."
  },
  "trend_zeitgeist": {
    "score": 75,
    "weight": 0.20,
    "details": "Aligns well with current minimalist aesthetic trends..."
  },
  "recommendations": [
    "Try adjusting the composition to follow the rule of thirds more closely",
    "Consider enhancing the lighting to create more dramatic shadows",
    "The color palette could be more vibrant to increase engagement"
  ],
  "user_preferences_used": null
}

Personalized Scoring (Y2K Fashion Influencer)

{
  "final_score": 85.2,
  "technical_quality": {
    "score": 85,
    "weight": 0.25,
    "details": "Image shows good sharpness and color balance..."
  },
  "compositional_strength": {
    "score": 72,
    "weight": 0.25,
    "details": "Subject is well-positioned but could benefit from..."
  },
  "psychological_engagement": {
    "score": 82,
    "weight": 0.30,
    "details": "Strong emotional appeal with engaging facial expressions..."
  },
  "trend_zeitgeist": {
    "score": 95,
    "weight": 0.20,
    "details": "Perfectly aligns with Y2K aesthetic for fashion content targeting Gen Z..."
  },
  "recommendations": [
    "The Y2K aesthetic is spot-on for your target audience",
    "Consider adding more vibrant, retro color filters to enhance the Y2K vibe",
    "The fashion elements align perfectly with Gen Z preferences"
  ],
  "user_preferences_used": {
    "aesthetic": "Y2K",
    "niche": "Fashion Influencer",
    "target_audience": "Gen Z",
    "content_type": "Instagram Post",
    "brand_voice": "Playful and Trendy"
  }
}

🎨 How the Scoring Works

Technical Quality Score (25%)

  • Sharpness & Focus (0-25 points): Image clarity and focus quality
  • Resolution & Clarity (0-25 points): Image resolution and overall clarity
  • Image Noise (0-20 points): Presence of noise and artifacts
  • Dynamic Range (0-15 points): Balance of highlights and shadows
  • Color Fidelity (0-15 points): Natural and well-balanced colors

Compositional Strength Score (25%)

  • Rule of Thirds (0-25 points): Subject positioning according to compositional rules
  • Leading Lines (0-20 points): Lines that guide the eye toward the subject
  • Balance & Symmetry (0-20 points): Visual balance and symmetry
  • Depth & Framing (0-20 points): Layering and framing effectiveness
  • Subject Isolation (0-15 points): How well the subject stands out

Psychological Engagement Score (30%)

  • Presence of Faces (0-30 points): Face detection and engagement
  • Emotional Resonance (0-25 points): Emotional impact and appeal
  • Color Psychology (0-25 points): Psychological impact of colors
  • Storytelling (0-20 points): Narrative elements and story potential

Trend & Zeitgeist Score (20%)

  • Aesthetic Alignment (0-60 points): Alignment with current visual trends
  • Authenticity Index (0-40 points): Genuine and authentic feel

🔧 Customization

You can modify the scoring weights in viral_velocity_scorer.py:

self.weights = {
    'technical_quality': 0.25,      # Change these values
    'compositional_strength': 0.25, # to adjust scoring
    'psychological_engagement': 0.30, # priorities
    'trend_zeitgeist': 0.20
}

📱 Next Steps for Mobile Integration

  1. API Integration: The mobile app can call the /score-image endpoint
  2. Image Enhancement: Add Gemini's image generation capabilities
  3. User Management: Add user authentication and usage tracking
  4. Analytics: Track scoring patterns and user engagement

🚨 Important Notes

  • Privacy: Images are processed temporarily and not stored
  • API Limits: Be mindful of OpenAI API usage limits and costs
  • Accuracy: Scores are AI-generated and should be used as guidance, not absolute truth
  • Mobile Optimization: Consider image compression for faster mobile processing
  • Performance: Uses efficient analysis (3 API calls instead of 8) to reduce costs
  • JSON Parsing: Automatically handles OpenAI's markdown-formatted JSON responses

🤝 Contributing

This is a data science-focused implementation. The scoring algorithms and AI integration are the core components. Frontend/backend development for the mobile app will be handled separately.

Built with ❤️ using OpenAI GPT-4 Vision for intelligent social media optimization

Reference in New Issue View Git Blame Copy Permalink