Skip to content

Commit

Permalink
chore: add docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Zyie
Zyie committed Jun 25, 2024
1 parent 14c0427 commit 05c4b12
Show file tree
Hide file tree
Showing 12 changed files with 296 additions and 109 deletions.
2 changes: 1 addition & 1 deletion packages/docs/docs/guide/configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 3
sidebar_position: 1
---

# Configuration
Expand Down
2 changes: 1 addition & 1 deletion packages/docs/docs/guide/pipes/_category_.yml
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
label: Optimisations
position: 1
position: 2
collapsed: false
48 changes: 0 additions & 48 deletions packages/docs/docs/guide/pipes/cache-buster.md
View file

This file was deleted.

59 changes: 59 additions & 0 deletions packages/docs/docs/guide/pipes/cache-buster.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
sidebar_position: 2
---

import { ImageToggle } from '@site/src/components/ImageToggle';

# Cache Buster

The `cacheBuster` plugin is an essential tool for ensuring that assets are correctly updated when they change.
When the `cacheBuster` plugin is added to the AssetPack configuration file, it generates unique hashes and appends them to file names.
This process ensures that when assets are modified, the updated versions are correctly re-downloaded by the user's browser, bypassing any cached versions.

## Example

<ImageToggle image={'cache/cache-buster'} height={350} />

To use the `cacheBuster` plugin, include it in your AssetPack pipeline.
It's crucial to note that the order of plugins in the pipeline affects the final output. For optimal results,
ensure that the `cacheBuster` transformation occurs at the correct stage in your pipeline.

```ts
// assetpack.config.ts
import { cacheBuster } from "assetpack";

export default {
...
pipes: {
...
// make sure these pipes are added after plugins that generate files
cacheBuster(),
},
};
```

## Spine and Texture Packer

When integrating with the [`texturePacker`](/docs/guides/pipes/texture-packer) plugin or your porject has spine atlas files,
you need to add the `texturePackerCacheBuster` / `spineAtlasCacheBuster` pipes immediately after the `cacheBuster` pipe.

The `texturePackerCacheBuster` ensures that the JSON files internally update their asset names to reflect the newly hashed file names.
The `spineAtlasCacheBuster` pipe performs a similar function for spine atlas files.

### Example

```ts
// assetpack.config.ts
import { cacheBuster, texturePackerCacheBuster, spineAtlasCacheBuster } from "assetpack";

export default {
...
pipes: {
...
// make sure these pipes are added after plugins that generate files
cacheBuster(),
texturePackerCacheBuster(),
spineAtlasCacheBuster(),
},
};
```
57 changes: 0 additions & 57 deletions packages/docs/docs/guide/pipes/ffmpeg.md
View file

This file was deleted.

79 changes: 79 additions & 0 deletions packages/docs/docs/guide/pipes/ffmpeg.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
sidebar_position: 2
---

import { ImageToggle } from '@site/src/components/ImageToggle';

# Audio & FFmpeg

The AssetPack library includes powerful plugins for audio conversion and file format manipulation using FFmpeg. These plugins, audio and ffmpeg, provide robust solutions for handling a variety of media file formats.

## Audio

The audio plugin converts and compresses audio files (`mp3`, `wav`, and `ogg`) to `mp3` and `ogg` formats. This is particularly useful for ensuring compatibility and optimizing file sizes for web delivery.

### Example

<ImageToggle image={'audio/audio'} height={350} />

```ts
// assetpack.config.ts
import { audio } from "assetpack";

export default {
...
pipes: [
audio: audio(),
],
};
```

## FFmpeg

The `ffmpeg` plugin exposes the full FFmpeg API, allowing for the conversion of any file type to any other file type. This provides a high level of customization and control over the conversion process, enabling a wide range of media processing tasks.

## API

The plugin takes an input array of file extensions and produces an output based on the options.

- `inputs`: An array of file extensions to be processed.
- `outputs`: An array of objects containing the output formats and options for each format.
- `formats`: An array of file extensions to be output.
- `recompress`: A boolean value indicating whether the input file should be compressed if the output format is the same as the input format.
- `options`: An object containing the FFmpeg options for the output file.

### Example

```ts
// assetpack.config.ts
import { ffmpeg } from "assetpack";

export default {
...
pipes: [
ffmpeg({
inputs: ['.mp3', '.ogg', '.wav'],
outputs: [
{
formats: ['.mp3'],
recompress: false,
options: {
audioBitrate: 96,
audioChannels: 1,
audioFrequency: 48000,
},
},
{
formats: ['.ogg'],
recompress: false,
options: {
audioBitrate: 32,
audioChannels: 1,
audioFrequency: 22050,
},
},
],
}),
],
};
```
138 changes: 138 additions & 0 deletions packages/docs/src/components/ImageToggle.tsx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
import { useState } from 'react';

export const Toggle = ({ toggleImage, showImage1 }) => (
<div style={{ width: '100%' }}>
<div
style={{
display: 'flex',
justifyContent: 'right',
alignItems: 'center',
width: '100%',
height: '100%',
padding: '10px',
}}
>
<p style={{ margin: '0 10px' }}>{showImage1 ? 'Original' : 'Processed'}</p>
<div
onClick={toggleImage}
style={{
position: 'relative',
width: '60px', // Width of the toggle
height: '30px', // Height of the toggle
backgroundColor: 'hsl(225 6% 13%)', // Background color of the toggle
borderRadius: '15px', // Makes it pill-shaped
cursor: 'pointer',
transition: 'background-color 0.3s',
border: '2px solid #696969', // Border color of the toggle
}}
>
<div
style={{
position: 'absolute',
top: '3px', // Small top margin to center vertically
left: showImage1 ? '5px' : '32px', // Moves the dot based on the toggle state
width: '20px', // Width of the dot
height: '20px', // Height of the dot
backgroundColor: showImage1 ? 'var(--ifm-color-secondary)' : 'var(--ifm-color-primary)', // Color of the dot
borderRadius: '50%', // Makes it circular
transition: 'left 0.3s', // Smooth transition for moving left and right
}}
/>
</div>
</div>
</div>
);

export const ImageToggle = ({ image, height }) =>
{
const [showImage1, setShowImage1] = useState(true);

const toggleImage = () =>
{
setShowImage1(!showImage1);
};

height ??= 600;
const image1 = `/assetpack/screenshots/${image}.png`;
const image2 = `/assetpack/screenshots/${image}-pro.png`;

return (
<div
style={{
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
width: '100%',
paddingBottom: '20px',
}}
>
<Toggle toggleImage={toggleImage} showImage1={showImage1} />
<div style={{ position: 'relative', pointerEvents: 'none', width: '100%', height }}>
<div
style={{
transition: 'opacity 0.5s ease-in-out',
opacity: showImage1 ? 1 : 0,
position: 'absolute',
width: '100%',
height: '100%',
}}
>
<div
style={{
width: '100%',
height: '100%',
margin: '0 auto',
display: 'flex',
justifyContent: 'center',
alignItems: 'center',
position: 'absolute',
}}
>
<img
src={image1}
alt="Input Image"
style={{
maxWidth: '100%',
maxHeight: '100%',
objectFit: 'contain',
boxShadow: '0 0 20px rgba(0, 0, 0, 0.5)',
}}
/>
</div>
</div>
<div
style={{
transition: 'opacity 0.5s ease-in-out',
opacity: showImage1 ? 0 : 1,
position: 'absolute',
width: '100%',
height: '100%',
}}
>
<div
style={{
width: '100%',
height: '100%',
margin: '0 auto',
display: 'flex',
justifyContent: 'center',
alignItems: 'center',
position: 'absolute',
}}
>
<img
src={image2}
alt="Processed Image"
style={{
maxWidth: '100%',
maxHeight: '100%',
objectFit: 'contain',
boxShadow: '0 0 20px rgba(0, 0, 0, 0.5)',
}}
/>
</div>
</div>
</div>
</div>
);
};
Loading

0 comments on commit 05c4b12

Please sign in to comment.