# How the Bulk Generate Feature Works in ACE-STEP-UI: Implementation and Safety Mechanisms > Learn how the bulk generate feature in ace-step-ui works. Discover its implementation and safety mechanisms, including randomized seeds and batch size limits for secure song creation. - Repository: [fspecii/ace-step-ui](https://github.com/fspecii/ace-step-ui) - Tags: how-to-guide - Published: 2026-04-29 --- **The bulk generate feature in ace-step-ui initiates multiple song generation jobs through a client-side loop that automatically randomizes seeds after the first job, limits batch sizes to preset maximums, and resets the counter post-execution to prevent accidental massive queues.** The bulk generate feature in the `fspecii/ace-step-ui` repository allows users to queue multiple AI-generated songs simultaneously while enforcing strict safety boundaries to protect both user experience and backend resources. Implemented entirely within the React frontend, this feature leverages a controlled iteration pattern in [`components/CreatePanel.tsx`](https://github.com/fspecii/ace-step-ui/blob/main/components/CreatePanel.tsx) that transforms a single user click into multiple distinct API calls. Understanding this implementation reveals how the application prevents duplicate outputs, limits server load, and maintains predictable UI state throughout the generation lifecycle. ## UI Controls and State Persistence The bulk generation interface presents users with a constrained selection of preset values to prevent uncontrolled resource consumption. In [`components/CreatePanel.tsx`](https://github.com/fspecii/ace-step-ui/blob/main/components/CreatePanel.tsx) at lines 1934–1950, the UI renders a button group allowing selection of exactly five options: 1, 2, 3, 5, or 10 concurrent jobs. ```tsx {/* Bulk Generate */}
{[1, 2, 3, 5, 10].map((count) => ( ))}
``` The component initializes the `bulkCount` state by checking `localStorage` for a persisted preference, defaulting to 1 if none exists. This occurs at lines 163–166: ```tsx const [bulkCount, setBulkCount] = useState(() => { const stored = localStorage.getItem('ace-bulkCount'); return stored ? Number(stored) : 1; }); ``` A separate `randomSeed` boolean (line 168) tracks whether the user desires deterministic output. When `randomSeed` is `false`, the system applies special handling to ensure the first job uses the explicit seed while subsequent jobs receive fresh random values to prevent identical outputs. ## The Generation Loop Architecture When the user triggers creation, the `handleGenerate` function executes a **for-loop** that iterates precisely `bulkCount` times (lines 976–1005). Each iteration constructs an independent generation payload and invokes the `onGenerate` callback, which ultimately dispatches to [`services/api.ts`](https://github.com/fspecii/ace-step-ui/blob/main/services/api.ts). ```tsx // Bulk generation: loop bulkCount times for (let i = 0; i < bulkCount; i++) { // Seed handling – first job can reuse the explicit seed, later jobs get fresh seeds let jobSeed = -1; if (!randomSeed && i === 0) { jobSeed = seed; // user‑provided seed on the first job } else if (!randomSeed && i > 0) { jobSeed = Math.floor(Math.random() * 4294967295); // random seed for variety } onGenerate({ … randomSeed: randomSeed || i > 0, // force random for every job after the first one seed: jobSeed, … }); } ``` This architecture ensures the backend receives discrete, fully-formed requests rather than a single batch command, distributing responsibility for safety checks between the client logic and the individual API transactions. ## Safety Mechanisms and Duplicate Prevention The bulk generate implementation incorporates four distinct safety layers to prevent resource exhaustion and user confusion. ### Deterministic Seed Protection To prevent identical outputs when users disable random seeding, the system applies conditional logic within the generation loop. **Only the first iteration** (`i === 0`) retains the user-specified seed value. All subsequent iterations automatically generate a cryptographically random 32-bit integer seed (`Math.floor(Math.random() * 4294967295)`) and force `randomSeed: true` in the payload. This guarantees variation across the batch even when the user requests deterministic mode. ### Batch Size Constraints The UI strictly limits `bulkCount` to the preset array `[1, 2, 3, 5, 10]`. Because the interface provides buttons rather than free-form input, users cannot specify arbitrary large values that might overwhelm the server or consume excessive compute credits. This hard ceiling of 10 serves as the primary circuit breaker against accidental massive queues. ### Job Isolation and Metadata Each job receives a uniquely suffixed title when `bulkCount > 1`, appending `(n)` to distinguish iterations (e.g., "My Song (2)"). This occurs within the payload construction phase of the generation loop, preventing identical filenames that could overwrite each other or confuse the user. Additionally, the `randomSeed` parameter is boolean-coerced to `true` for every job after the first (`randomSeed || i > 0`), ensuring the backend processing pipeline treats subsequent jobs as explicitly non-deterministic. ### Post-Operation State Reset Immediately after the loop completes, the component executes a cleanup routine at lines 1055–1058 to prevent accidental repeated bulk operations: ```tsx // Reset bulk count after generation if (bulkCount > 1) { setBulkCount(1); } ``` This guarantees that the next "Create" click generates only a single song, requiring the user to explicitly re-select a bulk quantity for subsequent batches. ## API Integration and Payload Structure The bulk feature reuses the existing single-song generation pipeline. The `onGenerate` function (defined externally and passed as a prop) typically invokes the API endpoint defined in [`services/api.ts`](https://github.com/fspecii/ace-step-ui/blob/main/services/api.ts). Each iteration produces an independent HTTP request with the following structure for the second job in a batch: ```json { "title": "My Song (2)", "randomSeed": true, "seed": -1, "batchSize": 1, "…": "other params from the UI" } ``` The [`i18n/translations.ts`](https://github.com/fspecii/ace-step-ui/blob/main/i18n/translations.ts) file provides localized strings for bulk UI elements (labels like `'bulkGenerate'`), ensuring the feature respects the application's internationalization requirements. To trigger a 5-job bulk generation programmatically: ```tsx setBulkCount(5); // UI equivalent of clicking the “5” button handleGenerate(); // Starts the loop described above ``` ## Summary - **The bulk generate feature** is implemented entirely client-side in [`components/CreatePanel.tsx`](https://github.com/fspecii/ace-step-ui/blob/main/components/CreatePanel.tsx) as a controlled loop over the `bulkCount` state. - **Safety constraints** include a hard UI limit of 10 jobs, automatic seed randomization after the first iteration, and mandatory title suffixing to distinguish outputs. - **State hygiene** is maintained by resetting `bulkCount` to 1 immediately after the generation loop completes, preventing accidental repeated bulk operations. - **Backend isolation** occurs because each job dispatches as a separate API call via [`services/api.ts`](https://github.com/fspecii/ace-step-ui/blob/main/services/api.ts), allowing the server to process bulk requests as independent, stateless tasks. ## Frequently Asked Questions ### How does the bulk generate feature prevent duplicate songs when using a fixed seed? When `randomSeed` is disabled, the system explicitly checks the iteration index within the generation loop. The first job (`i === 0`) uses the user-provided seed value, but all subsequent jobs automatically receive a fresh random 32-bit integer seed and have their `randomSeed` parameter forced to `true` in the payload. This ensures variation across the batch while respecting the user's deterministic request for the initial output. ### What is the maximum number of songs that can be generated in one bulk operation? The UI enforces a strict maximum of **10 songs** per bulk operation. The interface renders only preset buttons for values `[1, 2, 3, 5, 10]`, preventing users from entering arbitrary large numbers that could exhaust server resources or generate unexpected costs. ### Why does the bulk count reset to 1 after generation completes? The component resets `bulkCount` to 1 immediately after the `handleGenerate` loop finishes (lines 1055–1058) as a safety measure against accidental repeated clicks. Without this reset, a user who just generated 10 songs might inadvertently queue another 10 on their next interaction if they forgot to manually reduce the count, potentially causing resource waste and user frustration. ### Where is the bulk generate logic located in the codebase? The primary implementation resides in [`components/CreatePanel.tsx`](https://github.com/fspecii/ace-step-ui/blob/main/components/CreatePanel.tsx), specifically between lines 163–166 (state initialization), lines 976–1005 (the generation loop with seed logic), and lines 1055–1058 (post-generation reset). The feature relies on [`services/api.ts`](https://github.com/fspecii/ace-step-ui/blob/main/services/api.ts) for the actual network requests and [`i18n/translations.ts`](https://github.com/fspecii/ace-step-ui/blob/main/i18n/translations.ts) for localized UI text.