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

npm install @softroniclabs_platforms/music-game-sdk

Quick Start

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:

{
  "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

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

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:

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)

<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for voice-controlled music games</string>

Android (AndroidManifest.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:

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.