npm package: @softroniclabs_platforms/music-games-sdk
Description: A React Native SDK for integrating musical games into mobile applications. The SDK provides content-driven music games that can be customized with your own API endpoints.
Latest version: 1.0.4

# Music Game SDK

A React Native SDK for integrating musical games into mobile applications. The SDK provides content-driven music games that can be customized with your own API endpoints.

## Features

- 🎮 **Multiple Games**: FlappyBird, GraphPitch, and VocalTraining games
- 🎵 **Music Content API**: Fetch musical content from your backend
- 🎤 **Voice Control**: Advanced pitch detection and microphone management
- 📱 **React Native**: Built for mobile-first experiences
- 🔧 **Configurable**: Customize API endpoints and game settings

## Installation

```bash
npm install @softroniclabs_platforms/music-game-sdk
```

## Quick Start

```tsx
import React from 'react';
import { MusicGameSDK, GameType } from '@softroniclabs_platforms/music-game-sdk';

const App = () => {
  const config = {
    apiBaseUrl: 'https://your-api.com/api',
    apiTimeout: 10000,
    defaultHeaders: {
      'Authorization': 'Bearer your-token',
    },
  };

  const handleGameComplete = (score: number, stats: any) => {
    console.log('Game completed with score:', score);
    console.log('Game stats:', stats);
  };

  const handleGameError = (error: string) => {
    console.error('Game error:', error);
  };

  return (
    <MusicGameSDK
      contentId="your-content-id"
      gameId={GameType.FLAPPY_BIRD}
      config={config}
      onGameComplete={handleGameComplete}
      onGameError={handleGameError}
    />
  );
};

export default App;
```

## API Configuration

The SDK requires a backend API that provides musical content. Your API should implement the following endpoint:

### GET /content/{contentId}

Returns musical content in the following format:

```json
{
  "data": {
    "id": "content-id",
    "title": "Song Title",
    "description": "Song description",
    "tempo": 120,
    "notes_data": {
      "instrument": "piano",
      "key_signature": "C major",
      "time_signature": "4/4",
      "notes": {
        "pitch": "C3,D3,E3,F3,G3",
        "duration": "quarter,quarter,quarter,quarter,half"
      },
      "metadata": {
        "composer": "Composer Name",
        "loop": false
      }
    },
    "tags": ["piano", "beginner"],
    "is_public": true,
    "access_type": "free"
  }
}
```

## Games Available

### FlappyBird (`GameType.FLAPPY_BIRD`)
A voice-controlled flappy bird game where players must sing the correct pitch to navigate through pipes.

### GraphPitch (`GameType.GRAPH_PITCH`) 
A pitch visualization game that shows real-time pitch detection and musical note mapping.

### VocalTraining (`GameType.VOCAL_TRAINING`)
A vocal training game focused on pitch accuracy and musical education.

## Configuration Options

```tsx
interface MusicGameSDKConfig {
  apiBaseUrl: string;                    // Your API base URL
  apiTimeout?: number;                   // Request timeout (default: 10000ms)
  defaultHeaders?: Record<string, string>; // Default headers for API calls
  microphoneSettings?: {
    enableAdvancedFiltering?: boolean;   // Enable advanced audio filtering
    pitchDetectionSettings?: any;        // Custom pitch detection settings
  };
}
```

## Props

```tsx
interface MusicGameSDKProps {
  contentId: string;                     // ID of content to fetch from your API
  gameId: GameType;                     // Which game to launch
  config: MusicGameSDKConfig;           // SDK configuration
  onGameComplete?: (score: number, stats: any) => void; // Called when game ends
  onGameError?: (error: string) => void; // Called on errors
  style?: any;                          // Custom styling for the game container
}
```

## Advanced Usage

### Using Individual Components

You can also use individual game components with custom providers:

```tsx
import { 
  FlappyBirdGame, 
  ConfigProvider, 
  ContentProvider, 
  MicrophoneProvider 
} from '@softroniclabs_platforms/music-game-sdk';

const CustomApp = () => (
  <ConfigProvider config={myConfig}>
    <MicrophoneProvider settings={micSettings}>
      <ContentProvider contentId="my-content-id">
        <FlappyBirdGame 
          onGameComplete={handleComplete}
          onGameError={handleError}
        />
      </ContentProvider>
    </MicrophoneProvider>
  </ConfigProvider>
);
```

## Error Handling

The SDK provides comprehensive error handling:

- **Content Loading Errors**: API failures, network issues
- **Microphone Errors**: Permission denied, device not supported
- **Game Errors**: Invalid content, gameplay failures

All errors are reported through the `onGameError` callback.

## Microphone Permissions

The SDK requires microphone access for voice-controlled games. Make sure your app has the necessary permissions:

### iOS (Info.plist)
```xml
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for voice-controlled music games</string>
```

### Android (AndroidManifest.xml)
```xml
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

## Usage in Your Mobile App

Here's how to integrate the SDK into your React Native mobile application:

```tsx
import React, { useState } from 'react';
import { View, Button, Alert } from 'react-native';
import { MusicGameSDK, GameType } from '@softroniclabs_platforms/music-game-sdk';

const MyMobileApp = () => {
  const [showGame, setShowGame] = useState(false);
  const [contentId, setContentId] = useState('your-content-id');
  const [gameType, setGameType] = useState(GameType.FLAPPY_BIRD);

  const config = {
    apiBaseUrl: 'https://your-backend-api.com/api',
    defaultHeaders: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
    },
  };

  const handleGameComplete = (score: number, stats: any) => {
    Alert.alert(
      'Game Complete!',
      `Final Score: ${score}`,
      [
        {
          text: 'Play Again',
          onPress: () => setShowGame(false),
        },
        {
          text: 'OK',
          onPress: () => setShowGame(false),
        },
      ]
    );
  };

  const handleGameError = (error: string) => {
    Alert.alert('Game Error', error);
    setShowGame(false);
  };

  if (showGame) {
    return (
      <MusicGameSDK
        contentId={contentId}
        gameId={gameType}
        config={config}
        onGameComplete={handleGameComplete}
        onGameError={handleGameError}
        style={{ flex: 1 }}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: 'center', padding: 20 }}>
      <Button
        title="Play Flappy Bird Game"
        onPress={() => {
          setGameType(GameType.FLAPPY_BIRD);
          setShowGame(true);
        }}
      />
      <Button
        title="Play Graph Pitch Game"
        onPress={() => {
          setGameType(GameType.GRAPH_PITCH);
          setShowGame(true);
        }}
      />
      <Button
        title="Play Vocal Training"
        onPress={() => {
          setGameType(GameType.VOCAL_TRAINING);
          setShowGame(true);
        }}
      />
    </View>
  );
};

export default MyMobileApp;
```

## Support

For issues and questions, please create an issue on the GitHub repository.