README

At the current state, this is a wrapper package for AWS Rekognition with some extra handy methods.

💡 Usage

use Meema\MediaRecognition\Facades\Recognize;

// run any of the following methods:
// note: any of the detect*() method parameters are optional and will default to config values

// "image operations"
$recognize = Recognize::path('images/persons.jpg', 'image/jpeg'); // while the $mimeType parameter is optional, it is recommended for performance reasons
$recognize->detectLabels($minConfidence = null, $maxLabels = null)
$recognize->detectFaces($attributes = ['DEFAULT'])
$recognize->detectModeration($minConfidence = null)
$recognize->detectText()

// "video operations"
$recognize = Recognize::path('videos/amazing-video.mp4', 'video/mp4');
$recognize->startLabelDetection($minConfidence = null, $maxResults = 1000)
$recognize->startFaceDetection(string $faceAttribute = 'DEFAULT')
$recognize->startContentModeration(int $minConfidence = null)
$recognize->startTextDetection(array $filters = null)

// get the analysis/status of your jobs
$recognize->getLabelsByJobId(string $jobId)
$recognize->getFacesByJobId(string $jobId)
$recognize->getContentModerationByJobId(string $jobId)
$recognize->getTextDetectionByJobId(string $jobId)

// if you want to track your media recognitions, use the Recognizable trait on your media model && run the included migration
$media = Media::first();
$media->recognize($path)->detectFaces(); // you may chain any of the detection methods

🐙 Installation

You can install the package via composer:

composer require meema/laravel-media-recognition

The package will automatically register itself.

Next, publish the config file with:

php artisan vendor:publish --provider="Meema\MediaRecognition\Providers\MediaRecognitionServiceProvider" --tag="config"

Next, please add the following keys their values to your .env file.

AWS_ACCESS_KEY_ID=xxxxxxx
AWS_SECRET_ACCESS_KEY=xxxxxxx
AWS_DEFAULT_REGION=us-east-1
AWS_SNS_TOPIC_ARN=arn:aws:sns:us-east-1:000000000000:RekognitionUpdate
AWS_S3_BUCKET=bucket-name

The following is the content of the published config file:

return [
    /**
     * The fully qualified class name of the "media" model.
     */
    'media_model' => \App\Models\Media::class,

    /**
     * IAM Credentials from AWS.
     */
    'credentials' => [
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
    ],

    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),

    /**
     * Specify the version of the Rekognition API you would like to use.
     * Please only adjust this value if you know what you are doing.
     */
    'version' => 'latest',

    /**
     * The S3 bucket name where the image/video to be analyzed is stored.
     */
    'bucket' => env('AWS_S3_BUCKET'),

    /**
     * Specify the IAM Role ARN.
     *
     * You can find the Role ARN visiting the following URL:
     * https://console.aws.amazon.com/iam/home?region=us-east-1#/roles
     * Please note to adjust the "region" in the URL above.
     * Tip: in case you need to create a new Role, you may name it `Rekognition_Default_Role`
     * by making use of this name, AWS Rekognition will default to using this IAM Role.
     */
    'iam_arn' => env('AWS_IAM_ARN'),

    /**
     * Specify the AWS SNS Topic ARN.
     * This triggers the webhook to be sent.
     *
     * It can be found by selecting your "Topic" when visiting the following URL:
     * https://console.aws.amazon.com/sns/v3/home?region=us-east-1#/topics
     * Please note to adjust the "region" in the URL above.
     */
    'sns_topic_arn' => env('AWS_SNS_TOPIC_ARN'),

];

Preparing Your Media Model (optional)

This package includes a trait for your "Media model" that you may use to define the relationship of your media model with the tracked recognitions.

Simply use it as follows:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Meema\MediaRecognition\Traits\Recognizable;

class Media extends Model
{
    use Recognizable;

    // ...
}

Set Up Webhooks (optional)

This package makes use of webhooks in order to communicate the updates of the AWS Rekognition job. Please follow the following steps to enable webhooks for yourself.

Please note, this is only optional, and you should only enable this if you want to track the Rekognition job's results for long-lasting processes (e.g. analyzing video).

Setup Expose

First, let's use Expose to "expose" / generate a URL for our local API. Follow the Expose documentation on how you can get started and generate a "live" & sharable URL for within your development environment.

It should be as simple as cd my-laravel-api && expose.

Setup AWS SNS Topic & Subscription

Second, let's create an AWS SNS Topic which will notify our "exposed" API endpoint:

Open the Amazon SNS console at https://console.aws.amazon.com/sns/v3/home
In the navigation pane, choose Topics, and then choose "Create new topic".
For Topic name, enter RekognitionUpdate, and then choose "Create topic".

Copy & note down the topic ARN which you just created. It should look similar to this: arn:aws:sns:region:123456789012:RekognitionUpdate.
On the Topic details: RekognitionUpdate page, in the Subscriptions section, choose "Create subscription".
For Protocol, choose "HTTPS". For Endpoint, enter exposed API URL that you generated in a previous step, including the API URI.

For example,

https://meema-api.sharedwithexpose.com/api/webhooks/media-recognition

Choose "Create subscription".

Confirming Your Subscription

Finally, we need to ensure the subscription is confirmed. By navigating to the RekognitionUpdate Topic page, you should see the following section:

By default, AWS will have sent a post request to URL you defined in your "Subscription" setup. This package automatically handles the "confirmation" part. In case there is an issue and it is not confirmed yet, please click on the "Request confirmation" button as seen in the screenshot above.

You can also view the request in the Expose interface, by visiting the "Dashboard Url", which should be similar to: http://127.0.0.1:4040

Once the status reflects "Confirmed", your API will receive webhooks as AWS provides updates.

Deploying to Laravel Vapor

Please note, as of right now, you cannot reuse the AWS credentials stored in your "environment file". The "workaround" for this is to adjust the media-recognition.php-config file by renaming

From: AWS_ACCESS_KEY_ID - To: e.g. VAPOR_ACCESS_KEY_ID

From: AWS_SECRET_ACCESS_KEY - To: e.g. VAPOR_SECRET_ACCESS_KEY

and, lastly, please ensure that your Vapor environment has these values defined.

🧪 Testing

composer test

📈 Changelog

Please see our releases page for more information on what has changed recently.

💪🏼 Contributing

Please see CONTRIBUTING for details.

🏝 Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Media Recognition on GitHub

For casual chit-chat with others using this package:

Join the Meema Discord Server

🚨 Security

Please review our security policy on how to report security vulnerabilities.

🙏🏼 Credits

📄 License

The MIT License (MIT). Please see LICENSE for more information.

Made with ❤️ by Meema, Inc.

meema / laravel-media-recognition

Maintainers

Details