npm package: @socaity/media-toolkit
Description: Web-ready standardized file processing and serialization. Read, write, convert and send files. Including image, audio, video and any other file. Easily convert between base64, bytes, numpy and more. Create browser elements or use in node.js
Author: Socaity.ai
Latest version: 0.0.14


  <h1 align="center" style="margin-top:-25px">MediaToolkit-JS</h1>
<p align="center">
  <img align="center" src="docs/media-file-icon.png" height="200" />
</p>
  <h3 align="center" style="margin-top:-10px">Web-ready standardized file processing and serialization</h3>

We @[socaity.ai](https://www.socaity.ai) designed media-toolkit to work in a standardized way with all kind of media files across node.js, browser, and python environments. This SDK is designed to simplify the process of loading, manipulating, and exporting media files, making it an essential tool for developers working with multimedia content.

We use it to offer a simple unified approach for interacting with the [socaity APIs](https://www.socaity.ai/APIs/Overview) for generative AI.
Check-out our SDKs [socaity-js](https://github.com/SocAIty/socaity-js) and [socaity-python](https://github.com/SocAIty/socaity) to learn more about it.


## Key Features

- **Cross-Platform Compatibility**: Works effortlessly in Node.js, browser and python environments. See [media-toolkit-python](https://github.com/SocAIty/media-toolkit)
- **Versatile File Handling**: Supports various file types including images, audio, and video.
- **Easy Integration**: Simple API for loading files from local paths, URLs, base64 data, and binary data.
- **Advanced Processing**: Chain operations to create efficient file processing pipelines.
- **SEO Optimized**: Enhance your web applications with optimized media handling.
- **Lightweight & Fast** The package comes without additional dependencies and has just ~8kb.

## Getting Started

### Installation

Install the SDK via npm:

```bash
npm install @socaity/media-toolkit
```

## Usage

This section covers how to effectively work with files when using the SDK.

### Import
```typescript
import { MediaFile, ImageFile, AudioFile, VideoFile } from '@socaity/media-toolkit';
```
Or in browser environments
```html
<script src="media-toolkit.umd.js" />
```

### Loading Files

The SDK supports loading files from various sources:

```typescript
// From a local file path (Node.js only)
const imageFile = await MediaFile.create("./path/to/image.jpg");

// From a URL
const imageFromUrl = await MediaFile.create("https://example.com/image.jpg");

// From base64 data
const imageFromBase64 = await MediaFile.create("data:image/jpeg;base64,/9j/4AAQ...");

// From binary data (ArrayBuffer, Buffer, or Uint8Array)
const buffer = fs.readFileSync("./image.jpg");
const imageFromBuffer = await MediaFile.create(buffer);
```


### Saving and Exporting Files

After receiving results from Socaity APIs, you can easily save or export them:

```typescript
// Convert to different formats
const mf = await MediaFile.create("..")

const base64String = mf.toBase64(); // Returns data URI by default
const arrayBuffer = mf.toArrayBuffer();
const uint8Array = mf.toUint8Array();
const buffer = mf.toBuffer(); // In Node.js environments
const blob = mf.toBlob(); // In browser environments
```

### Embedding Media in Websites

For web applications, you can easily embed generated content. 
We imply that you have the [socaity SDK](https://github.com/SocAIty/socaity-js) installed 

```typescript
// Generate an image with Socaity API
const generatedImage = await socaity.text2img("A futuristic city");
// Create an image and append it to an element. This creates an <img src=".." > element.
document.getElementById('myImg').append(generatedImage.toImageElement())
// Or use in an existing HTML img
const imgElement = document.getElementById('myImg');
imgElement.src = generatedImage.toBase64();

```

### File Information and Manipulation

Retrieve and modify file metadata:

```typescript
// Get file information
const fileInfo = mediaFile.getInfo();
console.log(`Filename: ${fileInfo.fileName}`);
console.log(`Content type: ${fileInfo.contentType}`);
console.log(`Size: ${fileInfo.size} bytes`);
console.log(`Extension: ${fileInfo.extension}`);

// Check file size in different units
const sizeInKB = mediaFile.fileSize('kb');
const sizeInMB = mediaFile.fileSize('mb');

// Modify file metadata
mediaFile.setFileName("renamed_file.png");
mediaFile.setContentType("image/png");
```


### Sending Files to Socaity APIs

Once you have a `MediaFile` object, you can use it directly with any Socaity API endpoint:

```typescript
// Use with face swap API
const swappedFace = await socaity.swapImg2Img(sourceImage, targetImage);

// Use with text-to-image API for image-to-image processing
const prompt = "Transform this into a cyberpunk scene";
const enhancedImage = await socaity.text2img(prompt, "flux-schnell", {
  init_image: sourceImage,
  strength: 0.75
});
```

## Contributing

We welcome contributions from the community. Please read our [contributing guidelines](CONTRIBUTING.md) to get started.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Contact

For support or inquiries, please contact us at [support@socaity.ai](mailto:support@socaity.ai).

Stay updated with our latest news and releases by following us on [Twitter](https://twitter.com/socaity_ai) and [LinkedIn](https://www.linkedin.com/company/socaity-ai).

Happy coding!