Shots Studio Documentation

Welcome to the complete documentation for Shots Studio, your AI-powered screenshot management solution.

Getting Started

Shots Studio is an Android application that uses artificial intelligence to help you organize, search, and manage your screenshots. This guide will walk you through everything you need to know to get started.

What You'll Need

Android device running Android 8.0 (API level 26) or higher
Google Gemini API key (free to obtain)
Storage permissions for accessing screenshots
Internet connection for AI processing

Installation

Download the APK

Visit the Releases page on GitHub
Download the latest shots-studio-v1.x.x.apk file
On your Android device, enable "Install from unknown sources" in Settings
Open the downloaded APK file to install

⚠️ Security Notice

Only download APK files from official sources. Always verify the file integrity before installation.

First Launch

When you first launch Shots Studio, you'll be prompted to:

Grant storage permissions
Allow the app to access your device's screenshots
Set up your Gemini API key

API Setup

Getting Your Gemini API Key

Visit Google AI Studio
Sign in with your Google account
Click "Create API Key"
Copy the generated API key

Configuring the API Key in Shots Studio

Open Shots Studio
Tap the menu icon (☰) in the top-left corner
Select "Settings" → "API Key"
Paste your API key and tap "Save"

                    
// Example API key format:
AIzaSyBxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

💡 Privacy Note

Your API key is stored locally on your device and is only used to communicate with Google's Gemini API. Shots Studio never stores your data on external servers.

Features Guide

AI-Powered Analysis

Shots Studio uses Google's Gemini AI to analyze your screenshots and extract:

Text content - OCR extraction from images
Object detection - Identifying elements in screenshots
Context understanding - Understanding the purpose and content
Smart tags - Automatic categorization and tagging

Processing Screenshots

Tap the AI ⚡️ button in the top-right corner
Select screenshots to process (or process all)
Choose your AI model:
- Gemini 2.0 Flash - Fast processing, good for bulk operations
- Gemini 2.5 Pro - Detailed analysis, better for complex screenshots
Wait for processing to complete

Collections

Creating Collections

Collections help you group related screenshots for easy access:

Tap the "+" button on the main screen
Select "Create Collection"
Enter a name and description
Optionally enable "Auto-Add" for automatic population

Auto-Add Feature

When Auto-Add is enabled, new screenshots matching the collection criteria will be automatically added. The AI determines relevance based on:

Collection name and description
Existing screenshots in the collection
Content similarity analysis

Managing Collections

Add screenshots - Long-press screenshots and select "Add to Collection"
Remove screenshots - In collection view, long-press and select "Remove"
Edit collection - Tap the edit icon in collection header
Delete collection - In collection settings, tap "Delete Collection"

Search & Filtering

AI-Powered Search

Search your screenshots using natural language:

                    
// Example search queries:
"screenshots with code"
"images containing text about recipes"
"social media posts"
"screenshots from last week"
"images with phone numbers"
                    
                

Search Features

Content search - Find by text content within screenshots
Object search - Search for specific UI elements or objects
Date filtering - Filter by creation date
Tag filtering - Filter by AI-generated or manual tags
Collection filtering - Search within specific collections

Advanced Search Operators

tag:work - Find screenshots tagged with "work"
date:2024-01-01 - Find screenshots from specific date
collection:recipes - Search within "recipes" collection

Settings

API Configuration

API Key - Manage your Gemini API key
Default Model - Choose between Flash and Pro models
Processing Quality - Adjust image quality for API calls

Storage & Performance

Cache Management - Clear processed data cache
Thumbnail Quality - Adjust thumbnail generation settings
Background Processing - Enable processing in background

Privacy Settings

Data Retention - How long to keep processed data
Analytics - Anonymous usage analytics (opt-in)
Crash Reporting - Help improve the app

Troubleshooting

Common Issues

API Key Not Working

Verify the API key is correctly copied (no extra spaces)
Check that Gemini API is enabled in Google Cloud Console
Ensure you have sufficient API quota

Screenshots Not Processing

Check internet connection
Verify storage permissions are granted
Try processing smaller batches
Check API usage limits

App Crashing

Clear app cache in Android settings
Restart the app
Check available device storage
Update to latest version

Performance Optimization

Process screenshots in smaller batches
Use Gemini Flash for bulk operations
Clear cache periodically
Close other apps while processing

API Reference

Gemini API Integration

Shots Studio integrates with Google's Gemini API for AI processing. Here's how the integration works:

                    
// API Endpoint
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-pro-vision:generateContent

// Request Headers
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

// Request Body Example
{
  "contents": [{
    "parts": [
      {
        "text": "Analyze this screenshot and extract text content, identify objects, and suggest relevant tags."
      },
      {
        "inline_data": {
          "mime_type": "image/jpeg",
          "data": "base64_encoded_image_data"
        }
      }
    ]
  }]
}
                    
                

Response Format

The API returns structured data that Shots Studio processes to extract:

Extracted text content
Identified objects and UI elements
Suggested tags and categories
Content description and context

OCR (Optical Character Recognition) Feature

Overview

The OCR feature allows you to extract text from screenshots using the Tesseract OCR engine. This feature works completely offline and doesn't require internet connectivity.

Key Features

Text Extraction: Extracts text from screenshot images using Tesseract OCR
Offline Processing: Works completely offline without internet connectivity
Clipboard Integration: Automatically copies extracted text to clipboard
User-Friendly Dialog: Shows extracted text in a dialog for review
Platform Support: Available on Android and iOS

How to Use

Open any screenshot in the Screenshot Details screen
Click the text extraction button (🔤) in the bottom navigation bar
The app will process the image and extract any text found
A dialog will display the extracted text
Text is automatically copied to clipboard
You can copy the text again if needed

Supported Image Sources

File path-based images (mobile)
Byte array-based images (web)
Automatic temporary file creation when needed

Limitations

OCR accuracy depends on image quality and text clarity
Works best with clear, high-contrast text
Processing time depends on image size and complexity
Currently supports English by default (extensible to other languages)
No layout preservation (basic text extraction only)

💡 Pro Tip

For best OCR results, ensure your screenshots have clear, readable text with good contrast. Screenshots of documents, messages, or text-heavy content work particularly well.

Auto-Processing Safety Features

Overview

Shots Studio includes intelligent safety features that protect users from excessive resource usage during background AI processing. These features are model-specific and automatically monitor your device's battery and network conditions.

Battery Protection (Gemma Models)

When processing with Gemma models (which run locally on your device):

Monitoring: Battery level checked every 2 minutes
Threshold: Processing automatically stops when battery ≤ 20%
Reason: Gemma runs locally and can drain battery quickly
Notification: You'll see a specific "Gemma Processing Stopped" message

Network Protection (Gemini Models)

When processing with Gemini models (which use cloud API):

Monitoring: Detects network connectivity changes in real-time
Trigger: Stops when switching from WiFi to mobile data
Reason: Gemini uses cloud API and can consume significant mobile data
Notification: You'll see a specific "Gemini Processing Stopped" message

How It Works

When a safety condition is detected:

Background Service Detects Issue: Battery ≤20% (Gemma) or WiFi→Mobile (Gemini)
Processing Stops: Background processing is immediately halted
Notification Shown: You see a prominent safety notification
App UI Updated: The app receives the safety stop event and updates UI
Animation Stops: Processing animation stops immediately
User Informed: Appropriate message explains what happened

Key Benefits

No Stuck UI: App never shows "processing" when it's actually stopped
Clear Communication: You know exactly why processing stopped
Model-Specific: Different safety rules for different AI models
Instant Response: UI updates immediately when safety stop occurs
Zero Impact When Idle: Monitoring only active during processing

⚠️ Important Note

These safety features are designed to protect your battery and data usage. While you can restart processing after addressing the issue (charging or reconnecting to WiFi), the app prioritizes your device's health and your data plan.

Update Installer Feature

Overview

The update installer allows you to download and install app updates directly from within the app, without needing to manually download APK files from GitHub.

Key Features

Automatic Platform Detection: Only shows install option on Android devices
Download Progress: Real-time progress tracking during APK download
Permission Management: Automatically requests and handles install permissions
Error Handling: Graceful fallback to browser-based download if installation fails
File Size Display: Shows estimated download size before starting
Analytics Integration: Tracks user interactions with update dialogs

How It Works

Update Detection

The app automatically checks for updates by comparing your current version with the latest release on GitHub. You'll see an update dialog when a new version is available.

Installation Process (Android)

Permission Check: Verifies if the app has permission to install unknown apps
Permission Request: If not granted, redirects you to Android settings to enable it
APK Download: Downloads the APK file from GitHub releases with progress tracking
Installation: Uses Android's built-in APK installer to install the update
Cleanup: Temporary files are automatically handled by the system

Other Platforms

On non-Android platforms or if installation fails, the app provides a fallback option to open the GitHub releases page in your browser for manual download.

User Experience

For Android Users

Update dialog appears with "Install" button
Shows download size estimate
Click "Install" to start download
Real-time progress indicator
Automatic installation when download completes
Success message with instruction to restart

For Other Platforms

Update dialog appears with "Download" button
Click "Download" opens GitHub releases page in browser
Manually download and install

Security Considerations

APK files are downloaded directly from official GitHub releases
File integrity is verified by checking download size
Uses Android's built-in installation process for security
Temporary files are stored in app's cache directory
FileProvider ensures secure file access across apps

💡 First Time Setup

The first time you use the update installer, Android will prompt you to allow the app to install unknown apps. This is a standard security permission required for all apps that want to install APK files.

Contributing

Development Setup

Clone the repository:
git clone https://github.com/yourusername/shots-studio.git
Install Flutter SDK (version 3.10 or higher)
Install dependencies:
flutter pub get
Run the app:
flutter run

Project Structure

                    
lib/
├── main.dart              # App entry point
├── models/               # Data models
│   ├── screenshot_model.dart
│   ├── collection_model.dart
│   └── gemini_model.dart
├── screens/              # UI screens
│   ├── home_screen.dart
│   ├── search_screen.dart
│   └── settings_screen.dart
├── services/             # Business logic
│   ├── gemini_service.dart
│   ├── storage_service.dart
│   └── notification_service.dart
└── widgets/              # Reusable UI components
                    
                

Contributing Guidelines

Fork the repository and create a feature branch
Follow the existing code style and conventions
Add tests for new functionality
Update documentation as needed
Submit a pull request with detailed description

Reporting Issues

Found a bug or have a feature request? Please:

Check existing issues first
Provide detailed reproduction steps
Include device and Android version info
Attach relevant screenshots or logs

Server Messages

Shots Studio includes a robust server message system that allows for announcements, updates, and notifications to be delivered to users directly within the app.

What are Server Messages?

Server messages are notifications or dialogs that can be displayed in the app without requiring an app update. This system is used for:

Important announcements to all users
Version-specific feature updates
Critical service warnings
Maintenance notifications

Key Features

Version targeting: Messages can target specific app versions
Show-once functionality: Messages can be configured to show only one time
Expiration dates: Messages automatically expire after a specified date
Multiple message types: Info, Warning, Update messages with appropriate styling
Display modes: Messages can appear as dialogs or notifications

Technical Implementation

Messages are hosted in a static JSON file on GitHub Pages with a specified schema. For full technical details, see the SERVER_MESSAGES.md documentation.

{
  "version": "1.0",
  "last_updated": "2023-01-21T12:00:00Z",
  "messages": [
    {
      "show": true,
      "id": "welcome_message",
      "title": "Welcome to Shots Studio!",
      "message": "Thanks for downloading Shots Studio! Organize your screenshots like never before.",
      "type": "info",
      "priority": "medium",
      "show_once": true,
      "version": "ALL"
    }
  ]
}

Need more help? Contact our support team or open an issue on GitHub.